# Create field

`POST https://api.airtable.com/v0/meta/bases/{baseId}/tables/{tableId}/fields`

Creates a new column and returns the schema for the newly created column.

Refer to field types for supported [field types](https://airtable.com/developers/web/api/model/field-type.md), the write format for field options, and other specifics for certain field types. Supported field types have a write format shown.

## Requirements

- **Authentication:** [Personal access token](https://airtable.com/developers/web/api/authentication.md#types-of-token), [OAuth integration](https://airtable.com/developers/web/api/authentication.md#types-of-token)
- **Scope:** [`schema.bases:write`](https://airtable.com/developers/web/api/scopes.md#schema-bases-write)
- **User role:** Base creator
- **Billing plans:** All plans

## Path parameters

- `baseId: string`

- `tableId: string`

## Request body

Request body is one of the following variants:

### Variant 1

- `name: string` — required

  The name for the field.

- `type: "autoNumber"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

### Variant 2

- `name: string` — required

  The name for the field.

- `type: "barcode"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

### Variant 3

- `name: string` — required

  The name for the field.

- `type: "button"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

### Variant 4

- `name: string` — required

  The name for the field.

- `type: "checkbox"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

- `options: object` — required

  - `color: "greenBright" | "tealBright" | "cyanBright" | "blueBright" | "purpleBright" | "pinkBright" | "redBright" | "orangeBright" | "yellowBright" | "grayBright"` — required

    The color of the checkbox.

  - `icon: "check" | "xCheckbox" | "star" | "heart" | "thumbsUp" | "flag" | "dot"` — required

    The icon name of the checkbox.

### Variant 5

- `name: string` — required

  The name for the field.

- `type: "createdBy"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

### Variant 6

- `name: string` — required

  The name for the field.

- `type: "createdTime"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

- `options: object` — required

  - `result: object` — optional

    This will always be a `date` or `dateTime` field config.

### Variant 7

- `name: string` — required

  The name for the field.

- `type: "count"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

- `options: object` — required

  - `isValid: boolean` — required

    `false` when recordLinkFieldId is null, e.g. the referenced column was deleted.

  - `recordLinkFieldId: string | null` — optional

### Variant 8

- `name: string` — required

  The name for the field.

- `type: "formula"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

- `options: object` — required

  - `formula: string` — required

    The formula including fields referenced by their IDs. For example, LEFT(4, {Birthday})
    in the Airtable.com formula editor will be returned as LEFT(4, {fldXXXXXXXXXXXXXX}) via API.

  - `isValid: boolean` — required

    `false` if the formula contains an error.

  - `referencedFieldIds: array<string> | null` — required

    All fields in the record that are used in the formula.

  - `result` — [Field type and options](https://airtable.com/developers/web/api/field-model.md) | null — required

    The resulting field type and options returned by the formula. See other field
    type configs on this page for the possible values. Can be null if invalid.

### Variant 9

- `name: string` — required

  The name for the field.

- `type: "lastModifiedTime"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

- `options: object` — required

  - `isValid: boolean` — required

    False if this formula/field configuation has an error

  - `referencedFieldIds: array<string> | null` — required

    The fields to check the last modified time of

  - `result: object | null` — required

    This will always be a `date` or `dateTime` field config.

### Variant 10

- `name: string` — required

  The name for the field.

- `type: "lastModifiedBy"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

### Variant 11

- `name: string` — required

  The name for the field.

- `type: "lookup"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

- `options: object` — required

  - `fieldIdInLinkedTable: string | null` — required

    The field in the linked table that this field is looking up.

  - `isValid: boolean` — required

    Is the field currently valid (e.g. false if the linked record field has
    been deleted)

  - `recordLinkFieldId: string | null` — required

    The linked record field in the current table.

  - `result` — [Field type and options](https://airtable.com/developers/web/api/field-model.md) | null — required

    The field type and options inside of the linked table. See other field
    type configs on this page for the possible values. Can be null if invalid.

### Variant 12

- `name: string` — required

  The name for the field.

- `type: "number"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

- `options: object` — required

  - `precision: number` — required

    Indicates the number of digits shown to the right of the decimal point for this field. (0-8 inclusive)

### Variant 13

- `name: string` — required

  The name for the field.

- `type: "percent"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

- `options: object` — required

  - `precision: number` — required

    Indicates the number of digits shown to the right of the decimal point for this field. (0-8 inclusive)

### Variant 14

- `name: string` — required

  The name for the field.

- `type: "currency"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

- `options: object` — required

  - `precision: number` — required

    Indicates the number of digits shown to the right of the decimal point for this field. (0-7 inclusive)

  - `symbol: string` — required

    Currency symbol to use.

### Variant 15

- `name: string` — required

  The name for the field.

- `type: "duration"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

- `options: object` — required

  - `durationFormat: "h:mm" | "h:mm:ss" | "h:mm:ss.S" | "h:mm:ss.SS" | "h:mm:ss.SSS"` — required

### Variant 16

- `name: string` — required

  The name for the field.

- `type: "multilineText"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

### Variant 17

- `name: string` — required

  The name for the field.

- `type: "phoneNumber"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

### Variant 18

- `name: string` — required

  The name for the field.

- `type: "rating"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

- `options: object` — required

  - `color: "yellowBright" | "orangeBright" | "redBright" | "pinkBright" | "purpleBright" | "blueBright" | "cyanBright" | "tealBright" | "greenBright" | "grayBright"` — required

    The color of selected icons.

  - `icon: "star" | "heart" | "thumbsUp" | "flag" | "dot"` — required

    The icon name used to display the rating.

  - `max: number` — required

    The maximum value for the rating, from 1 to 10 inclusive.

### Variant 19

- `name: string` — required

  The name for the field.

- `type: "richText"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

### Variant 20

- `name: string` — required

  The name for the field.

- `type: "rollup"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

- `options: object` — required

  - `fieldIdInLinkedTable: string` — optional

    The id of the field in the linked table

  - `recordLinkFieldId: string` — optional

    The linked field id

  - `result` — [Field type and options](https://airtable.com/developers/web/api/field-model.md) | null — optional

    The resulting field type and options for the rollup. See other field
    type configs on this page for the possible values. Can be null if invalid.

  - `isValid: boolean` — optional

  - `referencedFieldIds: array<string>` — optional

    The ids of any fields referenced in the rollup formula

### Variant 21

- `name: string` — required

  The name for the field.

- `type: "singleLineText"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

### Variant 22

- `name: string` — required

  The name for the field.

- `type: "email"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

### Variant 23

- `name: string` — required

  The name for the field.

- `type: "url"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

### Variant 24

- `name: string` — required

  The name for the field.

- `type: "externalSyncSource"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

- `options: object` — required

  - `choices: array<object>` — required

    - `id: string` — required

    - `color: string` — optional

      Optional when the select field is configured to not use colors.

      Allowed values: "blueLight2", "cyanLight2", "tealLight2", "greenLight2", "yellowLight2", "orangeLight2", "redLight2", "pinkLight2", "purpleLight2", "grayLight2", "blueLight1", "cyanLight1", "tealLight1", "greenLight1", "yellowLight1", "orangeLight1", "redLight1", "pinkLight1", "purpleLight1", "grayLight1", "blueBright", "cyanBright", "tealBright", "greenBright", "yellowBright", "orangeBright", "redBright", "pinkBright", "purpleBright", "grayBright", "blueDark1", "cyanDark1", "tealDark1", "greenDark1", "yellowDark1", "orangeDark1", "redDark1", "pinkDark1", "purpleDark1", "grayDark1"

    - `name: string` — required

### Variant 25

- `name: string` — required

  The name for the field.

- `type: "aiText"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

- `options: object` — required

  - `prompt: array<string | object>` — optional

    The prompt that is used to generate the results in the AI field, additional object
    types may be added in the future. Currently, this is an array of strings or objects that identify any fields interpolated into the prompt.

    The prompt will not currently be provided if this field config is within another
    fields configuration (like a lookup field)

  - `referencedFieldIds: array<string>` — optional

    The other fields in the record that are used in the ai field

    The referencedFieldIds will not currently be provided if this field config is within another
    fields configuration (like a lookup field)

### Variant 26

- `name: string` — required

  The name for the field.

- `type: "multipleRecordLinks"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

- `options: object` — required

  - `linkedTableId: string` — required

    The ID of the table this field links to

  - `viewIdForRecordSelection: string` — optional

    The ID of the view in the linked table
    to use when showing a list of records to select from

### Variant 27

- `name: string` — required

  The name for the field.

- `type: "singleSelect"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

- `options: object` — required

  - `choices: array<object>` — required

    - `id: string` — optional

      This is not specified when creating new options, useful when specifing existing
      options (for example: reordering options, keeping old options and adding new ones, etc)

    - `color: string` — optional

      Optional when creating an option.

    - `name: string` — required

### Variant 28

- `name: string` — required

  The name for the field.

- `type: "multipleSelects"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

- `options: object` — required

  - `choices: array<object>` — required

    - `id: string` — optional

      This is not specified when creating new options, useful when specifing existing
      options (for example: reordering options, keeping old options and adding new ones, etc)

    - `color: string` — optional

      Optional when creating an option.

    - `name: string` — required

### Variant 29

- `name: string` — required

  The name for the field.

- `type: "singleCollaborator"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

- `options: object` — optional

### Variant 30

- `name: string` — required

  The name for the field.

- `type: "multipleCollaborators"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

- `options: object` — optional

### Variant 31

- `name: string` — required

  The name for the field.

- `type: "date"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

- `options: object` — required

  - `dateFormat: object` — required

    - `format: "l" | "LL" | "M/D/YYYY" | "D/M/YYYY" | "YYYY-MM-DD"` — optional

      Format is optional when writing, but it must match
      the corresponding name if provided.

      (`l` for local, `LL` for friendly, `M/D/YYYY` for us, `D/M/YYYY` for european, `YYYY-MM-DD` for iso)

    - `name: "local" | "friendly" | "us" | "european" | "iso"` — required

### Variant 32

- `name: string` — required

  The name for the field.

- `type: "dateTime"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

- `options: object` — required

  - `timeZone: Timezone` — required

  - `dateFormat: object` — required

    - `format: "l" | "LL" | "M/D/YYYY" | "D/M/YYYY" | "YYYY-MM-DD"` — optional

      Format is optional when writing, but it must match
      the corresponding name if provided.

      (`l` for local, `LL` for friendly, `M/D/YYYY` for us, `D/M/YYYY` for european, `YYYY-MM-DD` for iso)

    - `name: "local" | "friendly" | "us" | "european" | "iso"` — required

  - `timeFormat: object` — required

    - `name: "12hour" | "24hour"` — required

    - `format: "h:mma" | "HH:mm"` — optional

### Variant 33

- `name: string` — required

  The name for the field.

- `type: "multipleAttachments"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

### Variant 34

- `name: string` — required

  The name for the field.

- `type: "formula"` — required

- `description: string` — optional

  The description for the field (optional). If present, must be a non-empty string no longer than 20,000 characters.

- `options: object` — required

  - `formula: string` — required

    The [formula](https://support.airtable.com/docs/formula-field-reference)
    expression. Field references can use field IDs (e.g., `{fldXXXXXXXXXXXXXX}`)
    or field names (e.g., `{My Field}`).

## Response format

- `id: string` — required

- `type: Field-Type` — optional

- `name: string` — required

- `description: string` — optional

- `options: unknown` — optional

### Example — Success response

```sh
curl -X POST "https://api.airtable.com/v0/meta/bases/{baseId}/tables/{tableId}/fields" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
--data '{
    "description": "Whether I have visited this apartment yet.",
    "name": "Visited",
    "options": {
      "color": "greenBright",
      "icon": "check"
    },
    "type": "checkbox"
  }'
```

```json
{
  "description": "Whether I have visited this apartment yet.",
  "id": "fldumZe00w09RYTW6",
  "name": "Visited",
  "options": {
    "color": "redBright",
    "icon": "star"
  },
  "type": "checkbox"
}
```