Custom fields add your own data to people, such as a lead source or a budget. The Custom fields API lets you list, create, edit and delete the fields defined on your team.
Scopes
| Scope | Access |
|---|---|
CRM_READ | List custom fields, and read custom_attributes on people |
CRM_WRITE | Create and edit custom fields, and set custom_attributes on people |
CRM_DELETE | Delete custom fields |
Define a field, then set its value
A custom field is only the definition. The values live on each person, under custom_attributes.
- Define the field with Create custom field, for example
Lead Sourceof typeTEXT. Note thekeyit returns, herelead_source. - Set its value with
custom_attributeson Create person or Update person:{ "custom_attributes": { "lead_source": "Webinar" } }. - Read it back from
custom_attributeson Get person and Search people.
Only the keys you send are written, and null clears a value. Key and type errors come back as CUSTOM_ATTRIBUTE_KEY_UNKNOWN and CUSTOM_ATTRIBUTE_VALUE_INVALID. People responses always include custom_attributes, with archived fields and empty values left out. Search cannot filter or sort on custom fields.
Field types
| Type | Notes |
|---|---|
TEXT | |
NUMBER | |
DATE | |
BOOLEAN | |
DROPDOWN | One value out of a fixed list of options, each with a key and a label. Fields synced from your CRM integrations can also be dropdowns. |
Keys
Each field has a key, derived from its label: lowercase, accents removed, runs of non-alphanumeric characters replaced by _, truncated to 64 characters. Lead Source becomes lead_source.
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. Creating a field beyond the limit for its type returns ATTRIBUTE_SLOTS_EXHAUSTED.
Editing and deleting fields
Update custom field changes the label, the description and the options of a dropdown. The key and the type never change. Fields synced from a CRM integration cannot be edited or deleted, and built-in fields such as name or company are not custom fields.
Custom fields are available on workspaces that use the new contact model. Other workspaces get a 404 TEAM_NOT_FOUND.