---
title: "API_AddField"
slug: "api-addfield"
updated: 2025-08-18T08:58:00Z
published: 2025-08-18T08:58:00Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.quickbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API_AddField

**Don't forget to check out our**[**JSON RESTful APIs**](https://developer.quickbase.com/)**, 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](/v1/docs/field-types).

## 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 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 |
| 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 |
| udata | A string value that you want returned. It will not be handled by Quickbase but it will be returned in the response. | no |

## 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](/v1/docs/error-codes) 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

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

```plaintext
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](/v1/docs/understanding-the-api-call-reference).

## Sample response

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