API_AddField

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

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.

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 type Quick Base 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 Quick Base but it will be returned in the response.

no

top

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 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>

 

Go back    |     |  

© 1999-2018 QuickBase, Inc. All rights reserved. Legal Notices.