Custom fields · Orbit Docs

Definitions and values

A custom field adds a structured attribute without changing the contact schema. Definitions live in field_definitions; values live in each record's JSONB custom_fields object. Definitions are workspace-specific and apply to contacts, organisations, projects, and tasks. Use fields_list with an optional entity filter to discover the appropriate definitions.

An administrator registers a key and its meaning once. Agents discover it with fields_list, then populate it. Unknown keys and values with the wrong type are rejected. Agents cannot create or change definitions.

Discover available fields

During beta, field definitions are managed by Orbit administrators. Self-service definition creation is not available in the account interface or MCP yet. Agents must use existing definitions; they cannot invent new keys on the fly.

Call fields_list with your workspace_id and an optional entity filter (contact, organisation, project or task) to inspect available keys, descriptions and types. The same key can have different definitions for different entity types.

Supported types

Type	Accepted values
`text`	A string of up to 2,048 characters.
`number`	A JSON number, not a numeric string.
`boolean`	JSON `true` or `false`, not text or integers.
`date`	A valid `YYYY-MM-DD` date.
`datetime`	ISO-style date/time with seconds and an explicit `Z` or offset.
`string_list`	Up to 20 strings, each up to 255 characters.

Each record supports at most 30 populated keys and 16 KiB of custom-field JSON. Null is not a valid field value or a deletion shortcut.

Patch values explicitly

If preferred_contact_method exists as a text field for contacts, call contacts_update:

{
  "workspace_id": "01900000-0000-7000-8000-000000000010",
  "id": "01900000-0000-7000-8000-000000000001",
  "expected_revision": 1,
  "idempotency_key": "contact-preference-001",
  "changes": {"custom_fields": {"preferred_contact_method": "email"}}
}

Only supplied custom-field keys change. Other custom fields remain intact. An empty object does not clear them. To remove a value, use remove_custom_fields on contacts_update:

{
  "workspace_id": "01900000-0000-7000-8000-000000000010",
  "id": "01900000-0000-7000-8000-000000000001",
  "expected_revision": 2,
  "idempotency_key": "contact-preference-remove-001",
  "remove_custom_fields": ["preferred_contact_method"]
}

A key cannot be set and removed in one request. All keys must be registered, including explicit removals. Removing a value preserves the definition.

Filter contacts

{"workspace_id": "01900000-0000-7000-8000-000000000010", "custom_fields": {"preferred_contact_method": "email"}}

Pass this to contacts_search, organisations_search, projects_search, or tasks_search, using a definition registered for that entity. Filters use typed equality and all supplied filters must match. Date/time custom values retain their supplied offset; equality compares the stored representation, not equivalent instants in different offsets. Missing values do not match. Only scalar fields support equality filters; string-list matching, nested queries, arbitrary query operators, and custom aggregations are deferred.