> ## Documentation Index > Fetch the complete documentation index at: https://docs.getaptly.com/llms.txt > Use this file to discover all available pages before exploring further. # Add a field > Adds a custom field to the board. Requires `update` permission and the key's "Edit Boards" access (off by default); a key's board allowlist still applies. Accepts the same field shape and allowed field types as `POST /api/boards` (relational and system types are rejected); `uuid` must not be reserved or already used on the board. ## OpenAPI ````yaml /openapi.yaml post /api/board/{boardId}/configuration/fields openapi: 3.0.3 info: title: Aptly API version: '1.1' description: | The Aptly API lets external systems work with boards, contacts, inboxes, tasks, files, and other Aptly resources. Most endpoints accept an API key in the `x-token` header. Some endpoints also accept a delegate token or partner bearer token, as shown in each operation's security requirements, and explicitly public endpoints require no credential. API keys are scoped to a company and may be restricted to specific boards and read, insert, or update permissions; requests outside those restrictions receive a 403 `FORBIDDEN` response. servers: - url: https://core-api.getaptly.com description: Production security: - ApiKeyHeader: [] paths: /api/board/{boardId}/configuration/fields: post: tags: - Board summary: Add a field description: > Adds a custom field to the board. Requires `update` permission and the key's "Edit Boards" access (off by default); a key's board allowlist still applies. Accepts the same field shape and allowed field types as `POST /api/boards` (relational and system types are rejected); `uuid` must not be reserved or already used on the board. operationId: addBoardField parameters: - name: boardId in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - name - type properties: name: type: string type: $ref: '#/components/schemas/NewBoardFieldType' uuid: type: string description: >- Optional key; must match `^[a-zA-Z][a-zA-Z0-9_]{0,63}$`. Generated when omitted. optional: type: boolean pinned: type: boolean defaultValue: type: string data: type: array description: Required (non-empty) for `singleselect` and `multiselect`. items: type: object required: - label properties: label: type: string uuid: type: string example: name: Priority type: singleselect data: - label: Low - label: High responses: '201': description: The created field. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/BoardField' '400': description: '`VALIDATION_ERROR` (per-field `meta.issues`) or a rule violation.' content: application/json: schema: $ref: '#/components/schemas/ValidationError' '401': description: Invalid or missing API key. '403': description: >- 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': description: Board (or field) not found. security: - ApiKeyHeader: [] - PartnerBearer: [] components: schemas: NewBoardFieldType: type: string description: > 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. enum: - 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 BoardField: type: object properties: uuid: type: string description: >- Unique field identifier — use this as the key when reading/writing card data. name: type: string description: Display name of the field. type: type: string description: >- 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`). 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: type: integer description: Display order (zero-based). optional: type: boolean description: Whether the field is optional on cards. archived: type: boolean description: Whether the field has been archived (hidden from the UI). ValidationError: type: object description: > Returned with HTTP 400 when the request body fails shape validation (wrong type, missing required field, malformed email/phone number, value out of bounds). `meta.issues` lists every offending field. properties: error: type: object properties: code: type: string enum: - VALIDATION_ERROR message: type: string example: One or more fields are invalid meta: type: object properties: issues: type: array items: type: object properties: field: type: string description: >- Dotted path to the offending property (for example `to.0.value`); empty for a problem with the body as a whole. example: to.0.value code: type: string description: >- Machine-readable issue code (for example `invalid_type`, `invalid_format`, `too_small`). example: invalid_format message: type: string example: must be a valid email address requestId: type: string securitySchemes: ApiKeyHeader: type: apiKey in: header name: x-token PartnerBearer: type: http scheme: bearer description: 'Partner token. Format: `Authorization: Bearer `' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.