API_AddField

Don't forget to check out our JSON RESTful APIs, they can help you utilize and extend Quickbase 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 Quickbase UI.)

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

Request parameters

Parameter

Value

Required?

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.

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 Quickbase field type. The eligible type names differ slightly from their counterparts in the Quickbase UI:

Quickbase UI: Field type	Quickbase API: Field type
Checkbox	checkbox
Date	date
Duration	duration
Email Address	email
File Attachment	file
Formula	(see the “mode” param)
Lookup	(see the “mode” param)
List - User	multiuserid
Multi-select Text	multitext
Numeric	float
Numeric - Currency	currency
Numeric - Percent	percent
Numeric - Rating	rating
Phone Number	phone
Report Link	dblink
Text	text
Time Of Day	timeofday
URL	url
User	userid

yes

udata

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

Response values

The response to this call contains the following:

Element Name	Value
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 Quickbase 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>

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.

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>