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
| Method | Path | Description |
|---|---|---|
GET | /custom-fields | List custom fields |
GET | /custom-fields/:id | Get a custom field |
POST | /custom-fields | Create a custom field |
PATCH | /custom-fields/:id | Update a custom field |
DELETE | /custom-fields/:id | Delete 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
| Field | Type | Description |
|---|---|---|
id | integer | Read-only. Unique ID. |
organization_id | integer | Organization that owns the field. Required on create. |
entity_type | string | Record type the field belongs to: contact, company, deal, ticket, reservation, sales_document or product. Required on create. |
name | string | Display name. Required on create. Must be unique (case-insensitive) among the organization's active fields of the same entity_type. |
key | string | Identifier 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. |
fieldType | string | One of text, textarea, number, date, time, datetime, boolean, select, multiselect, email, url, phone, file, multifile, image, currency, json. Required on create. |
isRequired | boolean | Whether the app requires a value. Required on create. |
options | array | Choices for select and multiselect, as { "value": string, "order": integer }. |
system_currency_id | integer | null | Currency of a currency field. Required for currency fields and must be a currency enabled in the organization. Cleared for other types. |
custom_field_category_id | integer | null | Category (group) the field is shown under in the app. |
position | integer | Sort order within the entity type. Defaults to the end of the list. |
created_at | string (date-time) | Read-only. Creation time. |
updated_at | string (date-time) | Read-only. Last update time. |
deleted_at | string (date-time) | null | Read-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.