curl --request POST \
--url https://core-api.getaptly.com/api/board/{boardId}/configuration/fields \
--header 'Content-Type: application/json' \
--header 'x-token: <api-key>' \
--data '
{
"name": "Priority",
"type": "singleselect",
"data": [
{
"label": "Low"
},
{
"label": "High"
}
]
}
'import requests
url = "https://core-api.getaptly.com/api/board/{boardId}/configuration/fields"
payload = {
"name": "Priority",
"type": "singleselect",
"data": [{ "label": "Low" }, { "label": "High" }]
}
headers = {
"x-token": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-token': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'Priority',
type: 'singleselect',
data: [{label: 'Low'}, {label: 'High'}]
})
};
fetch('https://core-api.getaptly.com/api/board/{boardId}/configuration/fields', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://core-api.getaptly.com/api/board/{boardId}/configuration/fields",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => 'Priority',
'type' => 'singleselect',
'data' => [
[
'label' => 'Low'
],
[
'label' => 'High'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-token: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://core-api.getaptly.com/api/board/{boardId}/configuration/fields"
payload := strings.NewReader("{\n \"name\": \"Priority\",\n \"type\": \"singleselect\",\n \"data\": [\n {\n \"label\": \"Low\"\n },\n {\n \"label\": \"High\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-token", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://core-api.getaptly.com/api/board/{boardId}/configuration/fields")
.header("x-token", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"Priority\",\n \"type\": \"singleselect\",\n \"data\": [\n {\n \"label\": \"Low\"\n },\n {\n \"label\": \"High\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://core-api.getaptly.com/api/board/{boardId}/configuration/fields")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"Priority\",\n \"type\": \"singleselect\",\n \"data\": [\n {\n \"label\": \"Low\"\n },\n {\n \"label\": \"High\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": {
"uuid": "<string>",
"name": "<string>",
"type": "<string>",
"position": 123,
"optional": true,
"startCard": true,
"archived": true
}
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "One or more fields are invalid",
"meta": {
"issues": [
{
"field": "to.0.value",
"code": "invalid_format",
"message": "must be a valid email address"
}
]
}
},
"requestId": "<string>"
}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.
curl --request POST \
--url https://core-api.getaptly.com/api/board/{boardId}/configuration/fields \
--header 'Content-Type: application/json' \
--header 'x-token: <api-key>' \
--data '
{
"name": "Priority",
"type": "singleselect",
"data": [
{
"label": "Low"
},
{
"label": "High"
}
]
}
'import requests
url = "https://core-api.getaptly.com/api/board/{boardId}/configuration/fields"
payload = {
"name": "Priority",
"type": "singleselect",
"data": [{ "label": "Low" }, { "label": "High" }]
}
headers = {
"x-token": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-token': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'Priority',
type: 'singleselect',
data: [{label: 'Low'}, {label: 'High'}]
})
};
fetch('https://core-api.getaptly.com/api/board/{boardId}/configuration/fields', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://core-api.getaptly.com/api/board/{boardId}/configuration/fields",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => 'Priority',
'type' => 'singleselect',
'data' => [
[
'label' => 'Low'
],
[
'label' => 'High'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-token: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://core-api.getaptly.com/api/board/{boardId}/configuration/fields"
payload := strings.NewReader("{\n \"name\": \"Priority\",\n \"type\": \"singleselect\",\n \"data\": [\n {\n \"label\": \"Low\"\n },\n {\n \"label\": \"High\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-token", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://core-api.getaptly.com/api/board/{boardId}/configuration/fields")
.header("x-token", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"Priority\",\n \"type\": \"singleselect\",\n \"data\": [\n {\n \"label\": \"Low\"\n },\n {\n \"label\": \"High\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://core-api.getaptly.com/api/board/{boardId}/configuration/fields")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"Priority\",\n \"type\": \"singleselect\",\n \"data\": [\n {\n \"label\": \"Low\"\n },\n {\n \"label\": \"High\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": {
"uuid": "<string>",
"name": "<string>",
"type": "<string>",
"position": 123,
"optional": true,
"startCard": true,
"archived": true
}
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "One or more fields are invalid",
"meta": {
"issues": [
{
"field": "to.0.value",
"code": "invalid_format",
"message": "must be a valid email address"
}
]
}
},
"requestId": "<string>"
}Headers
Required with a partner bearer token (board-admin): the company that owns the board.
Standard boards such as unit share one board UUID across companies, so the board is
looked up by UUID within this company. companyId in the request body or query string
is also accepted. A partner request without a company is rejected with MISSING_DATA
(400), and a board the company does not own is BOARD_NOT_FOUND (404). Ignored for API
keys, whose company comes from the key.
Body
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 | 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.
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