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,
"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); 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.
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,
"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>"
}Authorizations
Path Parameters
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 Optional key; must match ^[a-zA-Z][a-zA-Z0-9_]{0,63}$. Generated when omitted.
Required (non-empty) for singleselect and multiselect.
Show child attributes
Show child attributes
Response
The created field.
Show child attributes
Show child attributes