ChatGPT ↗
Claude ↗This page documents the canonical HTTP contract for this endpoint.
The developer-key route scope expression is leads:write|companies:write|deals:write. The handler also requires the write scope matching the field entity: leads:write for lead, companies:write for company, or deals:write for deal. The caller must also have user-admin or internal-admin permission. For a developer key, this permission is loaded from its creator; the scope alone is insufficient. Each options item has required value and label, with optional validated color. ai_autofill supports enabled, mode (basic/agent), prompt (maximum 8,000 chars), run_when_created, only_if_empty, allow_new_options, and depends_on. sync_to_leads_write_policy is manual, autofill_only, manual_or_autofill, or disabled. This handler returns the serialized definition JSON object. See the CRM field catalog for organization-defined fields and option values.
Body parameters
entity_typerequiredstring
lead, company, or deal.
labelrequiredstring
Non-empty, at most 80 characters.
data_typerequiredstring
text, number, date, boolean, select, or multi_select.
key· optionalstring
Optional normalized field key.
description· optionalstring
At most 2,000 characters.
options· optionalarray
CustomFieldOption items; defaults to an empty list.
is_filterable· optionalboolean
is_sortable· optionalboolean
is_searchable· optionalboolean
include_in_task_context· optionalboolean
Defaults false.
include_in_sequence_variables· optionalboolean
include_in_ai_context· optionalboolean
Defaults false.
ai_autofill· optionalobject
sync_to_leads_write_policy· optionalstring
manual, autofill_only, manual_or_autofill, or disabled.
| Name | Type | Description |
|---|---|---|
| entity_typerequired | string | lead, company, or deal. |
| labelrequired | string | Non-empty, at most 80 characters. |
| data_typerequired | string | text, number, date, boolean, select, or multi_select. |
| key | string | Optional normalized field key. |
| description | string | At most 2,000 characters. |
| options | array | CustomFieldOption items; defaults to an empty list. |
| is_filterable | boolean | - |
| is_sortable | boolean | - |
| is_searchable | boolean | - |
| include_in_task_context | boolean | Defaults false. |
| include_in_sequence_variables | boolean | - |
| include_in_ai_context | boolean | Defaults false. |
| ai_autofill | object | - |
| sync_to_leads_write_policy | string | manual, autofill_only, manual_or_autofill, or disabled. |
Errors
| Status | Meaning |
|---|---|
| 401 | Missing or invalid authentication. |
| 403 | The key lacks the write scope matching the field entity, or the authenticated user lacks user-admin permission. |
| 422 | Invalid field definition or enum value. |