Custom Fields API
The Custom Field object
A custom field definition adds a field to one record type: CONTACT, LEAD, DEAL or COMPANY. The value itself lives on each record, in its customFields object, under the definition's key.
| Field | Type | Notes |
|---|---|---|
id | string | The definition ID |
entity | string | CONTACT, LEAD, DEAL or COMPANY |
key | string | Machine key derived from the label, e.g. Deal size becomes deal_size. Fixed once created |
label | string | Shown on forms, up to 100 characters |
type | string | TEXT, TEXTAREA, NUMBER, DATE, CHECKBOX, SELECT, MULTISELECT, URL, EMAIL or PHONE. Fixed once created |
options | array of string | Allowed values for SELECT and MULTISELECT. Empty for other types |
required | boolean | When true, any create or update that sends custom fields for that record type must include a value |
order | integer | Position on the form |
createdAt, updatedAt | string (ISO 8601) | Timestamps |
Example
{
"id": "cmq5cfd00alk34567890",
"entity": "DEAL",
"key": "deal_size",
"label": "Deal size",
"type": "SELECT",
"options": ["Small", "Large"],
"required": false,
"order": 0,
"createdAt": "2026-09-27T14:02:00.000Z",
"updatedAt": "2026-09-27T14:02:00.000Z"
}On a deal, the value then reads "customFields": { "deal_size": "Large" }.
Scopes
| Scope | Allows |
|---|---|
read:custom-fields | GET /api/v1/custom-fields and GET /api/v1/custom-fields/{id} |
write:custom-fields | Create, update and delete definitions |