API_AddField

Don't forget to come by and check out our new RESTful JSON APIs, they can help you utilize and extend Quick Base with ease.

 

Overview

Use API_AddField to add a new field to a table. You invoke this call on a table-level dbid.

When you add a field using API_AddField, you specify the field type, but no other field properties. After you've added the field, you can use API_SetFieldProperties to set the properties of the new field and any default values. (You can't set field type using API_SetFieldProperties; if you want to change the field type after adding the field, you must use the Quick Base UI.)

The amount of data space consumed by a field depends on the field type.  Read more in the online help.

top

Request parameters

ParameterValueRequired?

add_to_forms

Specifies whether the field you are adding should appear at the end of any form with form properties set to "Auto-Add new fields."

Set this parameter to 1 if you want the field to appear on all forms with "Auto-Add new fields" enabled.

If the new field has a type of fkey or dblink, the form is set to display it as a report instead of as a link.

no

apptoken

A valid application token.

yes, if the application requires application tokens

label

Allows you to enter the name of the new field.

yes

mode

Specifies whether the field is a formula field or a lookup field. Valid values are:

  • virtual -- specifies that the field should be a formula field (of whatever type you specify). You can specify virtual mode for any field type.

  • lookup -- Specifies that the field is a Lookup field. You can specify lookup mode for text (Text) or float (Numeric) type fields.

The value for this parameter must be lowercase.

Required for lookup or formula fields

ticket

A valid authentication ticket. The authentication ticket is returned via the API_Authenticate call.

yes, one of:

  • ticket
  • username/password
  • user token

usertoken

user token

yes, one of:

  • ticket
  • username/password
  • user token

type

The Quick Base field type. The eligible type names differ slightly from their counterparts in the Quick Base UI:

Quick Base UI: Field typeQuick Base API: Field type
Checkboxcheckbox
Datedate
Durationduration
Email Addressemail
File Attachmentfile
Formula(see the “mode” param)
Lookup(see the “mode” param)
List - Usermultiuserid
Multi-select Textmultitext
Numericfloat
Numeric - Currencycurrency
Numeric - Percentpercent
Numeric - Ratingrating
Phone Numberphone
Report Linkdblink
Texttext
Time Of Daytimeofday
URLurl
Useruserid

yes

udata

A string value that you want returned. It will not be handled by Quick Base but it will be returned in the response.

no

top

Response values

The response to this call contains the following:

Element NameValue

action

The originating request, for example, API_AddField.

errcode

Identifies the error code, if any. (See the Error Codes appendix for a list of possible error codes.)

0 indicates that no error was encountered.

errtext

Text that explains the error code.

"No error" indicates that no error was encountered.

fid

The field ID. You can use this value in other API calls that manipulate this field or field values.

label

The name of the field as it appears in the Quick Base application UI.

udata

Optional. Contains any udata value supplied in the request.

Sample XML request

POST https://target_domain/db/target_dbid?
Content-Type: application/xml
Content-Length:
QUICKBASE-ACTION: API_AddField

<qdbapi>
  <label>Phone Number</label>
   <type>phone</type>
   <ticket>auth_ticket</ticket>
   <apptoken>app_token</apptoken>
</qdbapi>

top

URL alternative

https://target_domain/db/target_dbid?a=API_AddField&label=Phone+Number
&type=phone&ticket=auth_ticket&apptoken=app_token

where target_domain is the domain against which you are invoking this call, for example, quickbase.com. Read about this notation.

top

Sample response

<?xml version="1.0" ?>
<qdbapi>
   <action>API_AddField</action>
   <errcode>0</errcode>
   <errtext>No error</errtext>
   <fid>8</fid>
   <label>Phone Number</label>
</qdbapi>