---
title: "Add a field"
method: POST
path: "/api/board/{boardId}/configuration/fields"
tags: ["Board"]
---

# Add a field

`POST /api/board/{boardId}/configuration/fields`

## Request

- Base URL: `https://core-api.getaptly.com`
- URL: `https://core-api.getaptly.com/api/board/{boardId}/configuration/fields`
- Auth: one of:
  - API key in header `x-token`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/getaptly/apis/aptly-api/docs/api/board/:boardId/configuration/fields/post.ts> (a function with typed inputs; its response is checked against the schema)

Adds a custom field to the board. Requires `update` permission and the key's "Edit Boards"
access (off by default; not needed on a board that same key created); a key's board allowlist
still applies, except for a board that key created. Accepts the same field shape
and allowed field types as `POST /api/boards` (relational and system types are rejected;
use `POST /api/board/{boardId}/configuration/mirror-fields` for a mirror field);
`uuid` must not be reserved or already used on the board.

## Path parameters

- `boardId` string, required

## Request body

- object
  - `name` string, required
  - `type` 'string' | 'text' | 'rich-text' | 'number' | 'money' | 'percent' | 'multiplier' | 'boolean' | 'date' | 'datetime-local' | 'email' | 'emails' | 'tel' | 'phones' | 'url' | 'address' | 'person' | 'persons' | 'user' | 'file' | 'files' | 'heroImage' | 'embedVideo' | 'stringList' | 'tags' | 'singleselect' | 'multiselect' | 'checkboxlist', required: The field types that can be created through the API (`POST /api/boards` and `POST /api/board/{boardId}/configuration/fields`). The value column is what a card stores and what the card API (`POST /api/board/{boardId}`) accepts under the field's `uuid`. | `type` | Label | Card value | |---|---|---| | `string` | Short Text | string | | `text` | Long Text | string | | `rich-text` | Rich Text | string (HTML) | | `number` | Number | number | | `money` | Currency | decimal number in requests (`1500.5`); returned as `{ amount, currency }` | | `percent` | Percent | number | | `multiplier` | Multiplier | number | | `boolean` | Checkbox | boolean | | `date` | Date | date | | `datetime-local` | Date and Time | date | | `email` | Email | string | | `emails` | Multiple Emails | string[] | | `tel` | Phone Number | string | | `phones` | Multiple Phone Numbers | array of phone objects | | `url` | URL | string | | `address` | Address | address object | | `person` | Link to a Single Contact | `{ _id }` (or `null` to clear); the contact must exist | | `persons` | Link to Multiple Contacts | array of `{ _id }` | | `user` | Team Member | user id | | `file` | Single Attachment | file id | | `files` | Multiple Attachments | file ids | | `heroImage` | Cover Photo | file id (the card's Kanban thumbnail) | | `embedVideo` | Embed Video | video URL string | | `stringList` | Text List | string[] | | `tags` | Tags | string[] | | `singleselect` | Dropdown | the chosen option's label - **requires `data`** | | `multiselect` | Multiple Select | array of option labels - **requires `data`** | | `checkboxlist` | Task List | array of `{ _id, checked, title }` (no `data`) | Relational and system types (`relatedAptlets`, `mirror`, `location`, `unit`, `stageselect`, `calculation`, and similar) can't be created through the API; boards built in the Aptly app can still contain them and they appear when reading fields.
  - `uuid` string: Optional key; must match `^[a-zA-Z][a-zA-Z0-9_]{0,63}$`. Generated when omitted.
  - `optional` boolean
  - `pinned` boolean
  - `startCard` boolean: Show the field on the form when a card is created.
  - `defaultValue` string
  - `data` object[]: Required (non-empty) for `singleselect` and `multiselect`.
    - `label` string, required
    - `uuid` string

## Response `201`

The created field.

- object
  - `data` BoardField
    - `uuid` string: Unique field identifier — use this as the key when reading/writing card data.
    - `name` string: Display name of the field.
    - `type` string: Field type. Fields created through the API use one of the types in `NewBoardFieldType` (`string`, `text`, `rich-text`, `number`, `money`, `percent`, `multiplier`, `boolean`, `date`, `datetime-local`, `email`, `emails`, `tel`, `phones`, `url`, `address`, `person`, `persons`, `user`, `file`, `files`, `heroImage`, `embedVideo`, `stringList`, `tags`, `singleselect`, `multiselect`, `checkboxlist`). Mirror fields (a copy of another board's field) are added with `POST /api/board/{boardId}/configuration/mirror-fields` and take the mirrored field's type. Boards built in the Aptly app can also contain relational and system types, e.g. `stageselect`, `sourceselect`, `relatedAptlets`, `mirror`, `mirror-contact`, `location`, `unit`, `board`, `calculation`, `ai-computed`, `cardId`, `daysOpened`, `timeSince`, `qualified`, `lostReason`, `lostDetails`, `relatedEvents`, `relatedDocuments`, `contactType`, `teams`.
    - `position` integer: Display order (zero-based).
    - `optional` boolean: Whether the field is optional on cards.
    - `startCard` boolean: Whether the field is shown on the form when a card is created.
    - `archived` boolean: Whether the field has been archived (hidden from the UI).

## Other responses

- `400`: `VALIDATION_ERROR` (per-field `meta.issues`) or a rule violation.
- `401`: Invalid or missing API key.
- `403`: The key lacks `update` permission or the "Edit Boards" access, the board isn't API-enabled, or the field can't be changed (locked, standard, mirror or integration-managed).
- `404`: Board (or field) not found.

---

[API](https://skmtc.dev/getaptly/apis/aptly-api.md) - [All operations](https://skmtc.dev/getaptly/apis/aptly-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getaptly/apis/aptly-api/revisions/75c367e0b8e5?raw)