Board

Add a field

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.

post/api/board/{boardId}/configuration/fields

Request

Base URL
https://core-api.getaptly.com
Auth
- API key in header x-token
- or 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.

Path parameters

boardIdstring required

Request body

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

uuidstring

Optional key; must match ^[a-zA-Z][a-zA-Z0-9_]{0,63}$. Generated when omitted.

optionalboolean

pinnedboolean

startCardboolean

Show the field on the form when a card is created.

defaultValuestring

Response

The created field.

Changes

No recorded changes to this operation across all 1 revision of this API.