Custom fields

Custom fields are the extra properties your organization defines for contacts, companies, deals, tickets, reservations, sales documents and products. Each field has a key; you write values on a record with custom_fields_by_key using that key.

Endpoints

MethodPathDescription
GET/custom-fieldsList custom fields
GET/custom-fields/:idGet a custom field
POST/custom-fieldsCreate a custom field
PATCH/custom-fields/:idUpdate a custom field
DELETE/custom-fields/:idDelete a custom field

Reads are limited to your API key's organization. Pass organization_id and entity_type as filters to get the fields of one record type.

The custom field object

json

A currency field also returns a currency object with the formatting of its currency:

json

Fields

FieldTypeDescription
idintegerRead-only. Unique ID.
organization_idintegerOrganization that owns the field. Required on create.
entity_typestringRecord type the field belongs to: contact, company, deal, ticket, reservation, sales_document or product. Required on create.
namestringDisplay name. Required on create. Must be unique (case-insensitive) among the organization's active fields of the same entity_type.
keystringIdentifier used in custom_fields_by_key. Generated from name on create (lowercase, spaces to _, e.g. Membership level → membership_level) with a numeric suffix if taken. You may send your own key on create; it cannot be changed afterwards.
fieldTypestringOne of text, textarea, number, date, time, datetime, boolean, select, multiselect, email, url, phone, file, multifile, image, currency, json. Required on create.
isRequiredbooleanWhether the app requires a value. Required on create.
optionsarrayChoices for select and multiselect, as { "value": string, "order": integer }.
system_currency_idinteger | nullCurrency of a currency field. Required for currency fields and must be a currency enabled in the organization. Cleared for other types.
custom_field_category_idinteger | nullCategory (group) the field is shown under in the app.
positionintegerSort order within the entity type. Defaults to the end of the list.
created_atstring (date-time)Read-only. Creation time.
updated_atstring (date-time)Read-only. Last update time.
deleted_atstring (date-time) | nullRead-only. Set when the field is deleted.

Value formats

When writing custom_fields_by_key on a record, each value is validated against the field type: number and currency must be numbers, boolean true/false, date/time/datetime valid date or time strings, email a valid email, url a URL starting with http:// or https://, phone at least 7 digits, select one of the options values (case-insensitive) and multiselect an array of them.

Related

Report an issue with this documentation

Please log in to report issues with our documentation.