Custom Fields API

All endpoints require authentication and custom-fields tool permissions.

Supported Entity Types

Custom fields can be defined for: deal, company, contact, person, project, task, recruitment_job, recruitment_candidate.

Supported Field Types

text, textarea, number, date, select, multi_select, toggle, url, email, user, reference.

Field Definitions

List Definitions

GET /api/custom-fields/definitions

Permission: custom-fields / view

Query parameters:

Param	Type	Description
entity_type	string	Filter by entity type. Matches both legacy entity_type column and entity_types JSON array

Response: { definitions }

Ordered by entity_type, position, name.

Create Definition

POST /api/custom-fields/definitions

Permission: custom-fields / manage

Request body:

Field	Type	Description
entity_type	string	Primary entity type (required)
entity_types	string[]	Multiple entity types this field applies to
name	string	Field name (required)
field_type	string	One of the supported field types (required)
required	boolean	Whether the field is required
description	string	Field description
position	number	Sort order (default: 0)
select_options	array	Options for select/multi_select fields

Response: { definition } (201)

Reorder Definitions

PUT /api/custom-fields/definitions/reorder

Permission: custom-fields / manage

Bulk-reorders definitions by setting their position based on array index.

Request body:

Field	Type	Description
ids	string[]	Ordered array of definition IDs

Response: { ok: true }

Update Definition

PUT /api/custom-fields/definitions/:id

Permission: custom-fields / manage

System fields cannot be edited.

Path parameters:

Param	Type	Description
id	string	Definition ID

Request body:

Field	Type	Description
name	string	Field name
description	string	Field description
required	boolean	Whether the field is required
position	number	Sort order
select_options	array	Options for select fields
entity_types	string[]	Entity types this field applies to

Response: { definition }

Delete Definition

DELETE /api/custom-fields/definitions/:id

Permission: custom-fields / manage

System fields cannot be deleted.

Path parameters:

Param	Type	Description
id	string	Definition ID

Response: { ok: true }

Field Values

Get Values

GET /api/custom-fields/values/:entityType/:entityId

Permission: custom-fields / view

Returns all custom field values for a specific entity, joined with the field definition name and type.

Path parameters:

Param	Type	Description
entityType	string	Entity type
entityId	string	Entity ID

Response: { values }

Each value includes field_id, entity_type, entity_id, value (JSON-serialised), name, and field_type.

Upsert Values

PUT /api/custom-fields/values/:entityType/:entityId

Permission: custom-fields / update

Batch upserts custom field values for an entity. Uses ON CONFLICT to update existing values.

Path parameters:

Param	Type	Description
entityType	string	Entity type
entityId	string	Entity ID

Request body:

Field	Type	Description
values	array	Array of { field_id, value } objects. Values are JSON-serialised before storage

Response: { ok: true }