Custom Fields

Custom fields let you extend contacts and companies with additional data fields specific to your business. Define field schemas, then set values on individual records.

The Custom Field Definition Object

Field	Type	Description
id	uuid	Unique identifier
account_id	uuid	Account this field belongs to
entity_type	string	contact or company
label	string	Display label
field_type	string	Data type: text, number, date, boolean, enum
options	string[] | null	Allowed values (enum fields only)
required	boolean	Whether the field is required
display_order	integer	Sort order for UI display
created_at	datetime	Creation timestamp

Field Types

Type	Value Format	Example
text	String	"Enterprise"
number	Number	42
date	YYYY-MM-DD string	"2025-06-01"
boolean	Boolean	true
enum	String (from options)	"gold"

List Custom Field Definitions

Endpoint: custom-fields-list

Field	Type	Required	Description
entity_type	string	No	Filter by entity type (contact or company)

curl -X POST https://api.driftwoodapp.com/api/custom-fields-list \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"entity_type": "contact"}'

Get Custom Field Definition

Endpoint: custom-fields-get

Field	Type	Required	Description
id	uuid	Yes	Custom field definition ID

Create Custom Field Definition

Endpoint: custom-fields-create

Field	Type	Required	Description
entity_type	string	Yes	contact or company
label	string	Yes	Display label
field_type	string	Yes	text, number, date, boolean, or enum
options	string[]	Conditional	Required for enum fields
required	boolean	No	Default: false
display_order	integer	No	Default: 0

curl -X POST https://api.driftwoodapp.com/api/custom-fields-create \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "contact",
    "label": "Tier",
    "field_type": "enum",
    "options": ["bronze", "silver", "gold", "platinum"],
    "required": false,
    "display_order": 1
  }'

Update Custom Field Definition

Endpoint: custom-fields-update

Field	Type	Required	Description
id	uuid	Yes	Definition ID
label	string	No	New label
options	string[]	No	New options (enum only)
required	boolean	No	Update required flag
display_order	integer	No	Update sort order

Delete Custom Field Definition

Endpoint: custom-fields-delete

Field	Type	Required	Description
id	uuid	Yes	Definition ID

Caution

Deleting a custom field definition removes the definition only. Existing field values on records are preserved as orphaned data.

Using Custom Fields on Records

When creating or updating contacts and companies, pass custom field values as a JSON object keyed by the field definition ID:

curl -X POST https://api.driftwoodapp.com/api/contacts-create \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Smith",
    "custom_fields": {
      "field-def-uuid-for-tier": "gold",
      "field-def-uuid-for-score": 95
    }
  }'

Error Codes

Code	Description
custom_fields.invalid_request	Malformed request body
custom_fields.invalid_id	Invalid UUID format
custom_fields.not_found	Definition does not exist
custom_fields.invalid_entity_type	Must be: contact, company
custom_fields.label_required	Label is required
custom_fields.invalid_field_type	Must be: text, number, date, boolean, enum
custom_fields.options_required	Enum fields require options
custom_fields.internal	Server error