Contact Custom Fields
Manage custom field values for individual contacts. These endpoints allow you to get, set, and delete custom field values on specific contacts.
Overview
While the Custom Fields endpoints define the structure of custom fields, the Contact Custom Fields endpoints manage the actual values stored for each contact. A contact can have values for any of the defined custom fields.
Supported Field Types and Value Formats
| Field Type | Value Type | Example |
|---|---|---|
text | string | "Acme Inc" |
number | number | 42, 3.14 |
boolean | boolean | true, false |
date | string | "2025-01-15" |
datetime | string | "2025-01-15T10:30:00Z" |
select | string | "enterprise" |
list | array of strings | ["Webinar X", "Webinar Y"] |
Endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /contacts/{contactUuid}/custom-fields | Get all custom field values for a contact |
| PUT | /contacts/{contactUuid}/custom-fields/{fieldUuid} | Set a custom field value (replaces the whole value) |
| POST | /contacts/{contactUuid}/custom-fields/{fieldUuid}/items | Add a single element to a list field |
| DELETE | /contacts/{contactUuid}/custom-fields/{fieldUuid}/items | Remove a single element from a list field |
| DELETE | /contacts/{contactUuid}/custom-fields/{fieldUuid} | Remove a custom field value entirely |
Working with list fields
A list field holds multiple free-form string values. You can manage it two ways:
- Replace the whole list with
PUT .../custom-fields/{fieldUuid}by sending an array asvalue(also works via Update Contact bulkcustom_fields). - Add/remove single elements with the
.../itemsendpoints — ideal for event-driven updates (e.g. a webhook firing when a contact attends a meeting).
Constraints for list values: each element is a non-empty string up to 255 characters, max 100 elements per contact. Elements are trimmed and de-duplicated; order is preserved.