Body fields
| Field | Type | Required | Description |
|---|---|---|---|
label | string | yes | Display name, 1 to 255 characters, with at least one letter or digit |
type | string | yes | TEXT, NUMBER, DATE, BOOLEAN or DROPDOWN |
options | array | DROPDOWN only | At least one { label, key? } object. Rejected for other types |
A DROPDOWN field holds one value out of its options. An option without a key gets one derived from its label, the same way as the field key. Option labels must be unique within the field.
{
"label": "Lead status",
"type": "DROPDOWN",
"options": [{ "label": "Hot" }, { "label": "Cold" }]
}
Key derivation
The key is derived from the label: lowercase, accents removed, runs of non-alphanumeric characters replaced by _, truncated to 64 characters. Lead Source becomes lead_source.
A label that resolves to a built-in field key is rejected with ATTRIBUTE_KEY_RESERVED. The reserved keys are name, phone_numbers, company, job_title, emails, last_activity, website, created_at and updated_at.
Response
Returns 201 with the field. options is only present for DROPDOWN.
{
"data": {
"key": "lead_status",
"label": "Lead status",
"type": "DROPDOWN",
"options": [
{ "key": "hot", "label": "Hot" },
{ "key": "cold", "label": "Cold" }
],
"already_existed": false
}
}
Creating the same field twice
The call is safe to repeat. If a field with the same key and type already exists, the endpoint returns 201 with already_existed set to true and the label it was first created with. Nothing is created.
If the key exists with a different type, the request returns 409 ATTRIBUTE_KEY_CONFLICT.
Restoring a deleted field
Creating a field whose key matches a field you deleted, with the same type, restores it. The values previously stored on people come back with it, and the response has already_existed set to true. A different type returns 409 ATTRIBUTE_KEY_CONFLICT.
Limits
A team can hold up to 150 TEXT, 50 NUMBER, 30 DATE and 30 BOOLEAN custom fields. DROPDOWN fields count toward the TEXT limit. Once a type is full, creating another field of that type returns 409 ATTRIBUTE_SLOTS_EXHAUSTED.
Errors
| Status | Code | When |
|---|---|---|
400 | ATTRIBUTE_LABEL_INVALID | label is blank, longer than 255 characters, or has no letter or digit |
400 | ATTRIBUTE_KEY_RESERVED | The label resolves to a built-in field key |
400 | ATTRIBUTE_OPTION_INVALID | A DROPDOWN field has no options, or an option label is blank, longer than 255 characters or duplicated |
400 | ATTRIBUTE_OPTIONS_NOT_SUPPORTED | options sent for a type other than DROPDOWN |
400 | INVALID_REQUEST_BODY | type is missing or is not one of TEXT, NUMBER, DATE, BOOLEAN, DROPDOWN |
403 | API_KEY_INSUFFICIENT_SCOPE | The key does not hold CRM_WRITE |
404 | TEAM_NOT_FOUND | The workspace is not on the new contact model |
409 | ATTRIBUTE_KEY_CONFLICT | A field with this key already exists with another type |
409 | ATTRIBUTE_SLOTS_EXHAUSTED | No free slot is left for this type |