Custom Fields API

Extend the contact schema with typed fields specific to your business — lifetime_value, plan_tier, last_login_at, account_manager, etc. Custom fields are referenced from segment rules, flow conditions, message personalization, and the inbox UI. Base path: /api/v1/custom-fields Authentication: API key (X-API-Key) or session JWT.

Using the SDKs

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const res = await orbit.customFields.list();

The Python SDK doesn’t wrap custom fields — its client.request escape hatch defines a field and sets it on a contact (source-only; vendor it from packages/sdk-python):

from orbit_sdk import OrbitClient

client = OrbitClient.from_api_key("dv_test_sk_YOUR_KEY")
definition = client.request(
    "POST",
    "/custom-fields",
    json_body={
        "name": "Customer tier",
        "key": "customer_tier",
        "type": "select",
        "options": ["bronze", "silver", "gold"],
    },
)
written = client.request(
    "PUT",
    "/custom-fields/values",
    json_body={"contact_id": "cnt_9f8a7b6c", "key": "customer_tier", "value": "gold"},
)

Returns the typed ApiResponse envelope. See the SDK index at SDK quickstart.

Definitions

Method	Path	Purpose
`GET`	`/api/v1/custom-fields/`	List field definitions
`POST`	`/api/v1/custom-fields/`	Create a definition
`GET`	`/api/v1/custom-fields/{id}`	Get a definition
`GET`	`/api/v1/custom-fields/{id}/dependencies`	Scan which segments, campaigns, flows, and contacts reference the field
`GET`	`/api/v1/custom-fields/{id}/explorer`	Inspect a field: definition, usage counts, and its last 10 PII-redacted sample values
`PATCH`	`/api/v1/custom-fields/{id}`	Update name / description / options / validators
`DELETE`	`/api/v1/custom-fields/{id}`	Delete a definition and strip its values from every contact
`POST`	`/api/v1/custom-fields/reorder`	Reorder definitions for the dashboard UI

A field’s key and type are immutable: they are fixed at creation and cannot be changed by PATCH (changing either would orphan the values already stored on contacts). To switch a field’s type, delete it and create a new one.

Create a definition

POST /api/v1/custom-fields/ creates the definition and returns it with the server-assigned id, plus any options (required for select / multiselect) and validators you sent:

curl -X POST https://api.orbit.devotel.io/api/v1/custom-fields/ \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "customer_tier",
    "type": "select",
    "name": "Customer tier",
    "options": ["bronze", "silver", "gold"],
    "default_value": "bronze"
  }'

{
  "data": {
    "id": "cf_01J8Z9K3P4Q5R6S7T8U9V0W1X2",
    "name": "Customer tier",
    "key": "customer_tier",
    "type": "select",
    "description": null,
    "options": ["bronze", "silver", "gold"],
    "default_value": "bronze",
    "required": false,
    "searchable": true,
    "display_order": null,
    "validator_regex": null,
    "min_len": null,
    "max_len": null,
    "enum_values": null,
    "created_at": "2026-08-19T12:00:00.000Z",
    "updated_at": "2026-08-19T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_01J8Z9K3P4Q5R6S7T8U9V0W1X2",
    "timestamp": "2026-08-19T12:00:00.000Z"
  }
}

List definitions

GET /api/v1/custom-fields/ returns every definition in display order — display_order ascending, never-ordered fields trailing, then by key. A freshly provisioned tenant returns an empty list.

{
  "data": [
    {
      "id": "cf_01J8Z9K3P4Q5R6S7T8U9V0W1X2",
      "name": "Customer tier",
      "key": "customer_tier",
      "type": "select",
      "description": "Primary account segment.",
      "options": ["bronze", "silver", "gold"],
      "default_value": "bronze",
      "required": false,
      "searchable": true,
      "display_order": 0,
      "validator_regex": null,
      "min_len": null,
      "max_len": null,
      "enum_values": null,
      "created_at": "2026-08-01T09:00:00.000Z",
      "updated_at": "2026-08-12T15:30:00.000Z"
    },
    {
      "id": "cf_01J8Z9K3P4Q5R6S7T8U9V0W1X3",
      "name": "Account credits",
      "key": "account_credits",
      "type": "number",
      "description": null,
      "options": null,
      "default_value": "0",
      "required": false,
      "searchable": false,
      "display_order": 1,
      "validator_regex": null,
      "min_len": 0,
      "max_len": 100000,
      "enum_values": null,
      "created_at": "2026-08-02T10:15:00.000Z",
      "updated_at": "2026-08-02T10:15:00.000Z"
    }
  ],
  "meta": {
    "request_id": "req_01J8Z9K3P4Q5R6S7T8U9V0W1X2",
    "timestamp": "2026-08-19T12:00:00.000Z"
  }
}

Update a definition

PATCH /api/v1/custom-fields/{id} renames the field or updates its description, options, default value, required/searchable flags, and validators. key and type stay frozen — pass null on a validator or the default value to clear it.

curl -X PATCH https://api.orbit.devotel.io/api/v1/custom-fields/cf_01J8Z9K3P4Q5R6S7T8U9V0W1X2 \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "required": true, "options": ["bronze", "silver", "gold", "platinum"] }'

{
  "data": {
    "id": "cf_01J8Z9K3P4Q5R6S7T8U9V0W1X2",
    "name": "Customer tier",
    "key": "customer_tier",
    "type": "select",
    "description": "Primary account segment.",
    "options": ["bronze", "silver", "gold", "platinum"],
    "default_value": "bronze",
    "required": true,
    "searchable": true,
    "display_order": 0,
    "validator_regex": null,
    "min_len": null,
    "max_len": null,
    "enum_values": null,
    "created_at": "2026-08-01T09:00:00.000Z",
    "updated_at": "2026-08-19T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_01J8Z9K3P4Q5R6S7T8U9V0W1X2",
    "timestamp": "2026-08-19T12:00:00.000Z"
  }
}

Reorder definitions

Pass the list’s definition ids top-to-bottom; the response returns the refreshed list so you can reconcile in one round-trip. Unknown ids are ignored, omitted ids keep their current position.

curl -X POST https://api.orbit.devotel.io/api/v1/custom-fields/reorder \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "ordered_ids": ["cf_01J8Z9K3P4Q5R6S7T8U9V0W1X3", "cf_01J8Z9K3P4Q5R6S7T8U9V0W1X2"] }'

The response is the full definition list in the new order (same envelope as the list endpoint above).

Dependencies and explorer

Before you delete or repurpose a field, check what references it.

Dependency scan

GET /api/v1/custom-fields/{id}/dependencies returns the count of contacts holding a value plus the segments, campaigns, drip enrollments, and flows that reference the field — the same snapshot the 409 below carries on a guarded delete:

{
  "data": {
    "field_key": "customer_tier",
    "contacts_with_data": 45,
    "segments": [
      { "id": "seg_01J8Z9K3P4Q5R6S7T8U9V0W1X5", "name": "Gold tier customers" }
    ],
    "campaigns": [
      { "id": "cmp_01J8Z9K3P4Q5R6S7T8U9V0W1X6", "name": "Tier upgrade nudge" }
    ],
    "drip_enrollments": 12,
    "flows": [
      { "id": "flw_01J8Z9K3P4Q5R6S7T8U9V0W1X7", "name": "Tier-based welcome journey" }
    ]
  },
  "meta": {
    "request_id": "req_01J8Z9K3P4Q5R6S7T8U9V0W1X2",
    "timestamp": "2026-08-19T12:00:00.000Z"
  }
}

An unused field returns zero counts and empty arrays. The endpoint 404s only when the definition itself doesn’t exist.

Explorer payload

GET /api/v1/custom-fields/{id}/explorer returns the definition, the usage block (the same counts as the scan above, plus a total), and up to ten of the most recently written values — every sample is PII-redacted and tail-truncated to 120 characters:

{
  "data": {
    "definition": {
      "id": "cf_01J8Z9K3P4Q5R6S7T8U9V0W1X2",
      "name": "Customer tier",
      "key": "customer_tier",
      "type": "select",
      "options": ["bronze", "silver", "gold"],
      "default_value": "bronze",
      "required": false,
      "searchable": true
    },
    "usage": {
      "contacts_with_data": 45,
      "segments": [
        { "id": "seg_01J8Z9K3P4Q5R6S7T8U9V0W1X5", "name": "Gold tier customers" }
      ],
      "campaigns": [
        { "id": "cmp_01J8Z9K3P4Q5R6S7T8U9V0W1X6", "name": "Tier upgrade nudge" }
      ],
      "drip_enrollments": 12,
      "flows": [],
      "total": 59
    },
    "samples": ["gold", "silver", "bronze"]
  },
  "meta": {
    "request_id": "req_01J8Z9K3P4Q5R6S7T8U9V0W1X2",
    "timestamp": "2026-08-19T12:00:00.000Z"
  }
}

Use it to sanity-check what people are actually storing under a key before you narrow its options or validators.

Deleting a field that is in use

DELETE is guarded so you don’t silently break the segments, campaigns, and flows that reference a field. If the field is still referenced by any segment, campaign, or flow — or has values stored on any contact — the request returns 409 Conflict with code CUSTOM_FIELD_IN_USE. The response details list every dependent so you can review or clean up first:

{
  "error": {
    "code": "CUSTOM_FIELD_IN_USE",
    "message": "Field \"ltv_usd\" is referenced by 2 segment(s), 1 campaign(s), 0 flow(s) and stored on 431 contact(s). Pass force=true to delete and break dependents.",
    "details": {
      "field_key": "ltv_usd",
      "dependencies": {
        "segments": [ /* ... */ ],
        "campaigns": [ /* ... */ ],
        "flows": [ /* ... */ ],
        "contacts_with_data": 431
      }
    }
  }
}

To delete anyway, pass ?force=true:

curl -X DELETE "https://api.orbit.devotel.io/api/v1/custom-fields/cf_abc123?force=true" \
  -H "X-API-Key: dv_live_sk_your_key_here"

With force=true the delete proceeds: the field’s values are stripped from every contact, and each dependent is flagged so you can find it afterward. Dependent segments are set to status: "broken". Dependent campaigns keep running — an in-flight send is never interrupted — but are flagged with a broken_custom_fields marker in their metadata. Dependent flows are set to status: "broken" so the automation runner skips them. The reference to the deleted field is not stripped from the campaign or flow filter: the filter JSON is left intact and only flagged, so the stale field-leaf remains until you edit or rebuild the filter. A field that is not referenced anywhere deletes without needing force.

Values

Per-contact values are written via a single endpoint and read inline as part of the contact resource.

Method	Path	Purpose
`PUT`	`/api/v1/custom-fields/values`	Set a custom-field value on a contact

The value is validated against the definition — a wrong type or a violate-the-validator value returns 422. A successful write echoes the contact id and key with ok: true, and the next contact GET reflects the new value because the write invalidates the contact-detail cache:

{
  "data": {
    "contact_id": "cnt_abc123",
    "key": "ltv_usd",
    "ok": true
  },
  "meta": {
    "request_id": "req_set_value",
    "timestamp": "2026-08-24T09:16:00.000Z"
  }
}

On the contact, values come back inline in the custom_fields object — keyed by the field key:

{
  "data": {
    "id": "cnt_abc123",
    "phone": "+14155551234",
    "custom_fields": { "ltv_usd": 482.5 },
    "tags": ["vip"]
  },
  "meta": {
    "request_id": "req_get",
    "timestamp": "2026-08-24T09:17:00.000Z"
  }
}

The full contact-readback walk-through, including filter + pagination, is on the Contacts page.

Example — define a lifetime-value field, then set it

# 1. Define
curl -X POST https://api.orbit.devotel.io/api/v1/custom-fields/ \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "key": "ltv_usd", "type": "number", "name": "Lifetime value (USD)" }'

# 2. Set on a contact
curl -X PUT https://api.orbit.devotel.io/api/v1/custom-fields/values \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "contact_id": "cnt_abc123", "key": "ltv_usd", "value": 482.50 }'

API Reference

All Endpoints

Custom Fields API: typed contact metadata

Custom Fields API

Using the SDKs

Definitions

Create a definition

List definitions

Update a definition

Reorder definitions

Dependencies and explorer

Dependency scan

Explorer payload

Deleting a field that is in use

Values

Example — define a lifetime-value field, then set it

See also

​Custom Fields API

​Using the SDKs

​Definitions

​Create a definition

​List definitions

​Update a definition

​Reorder definitions

​Dependencies and explorer

​Dependency scan

​Explorer payload

​Deleting a field that is in use

​Values

​Example — define a lifetime-value field, then set it

​See also

Custom Fields API

Using the SDKs

Definitions

Create a definition

List definitions

Update a definition

Reorder definitions

Dependencies and explorer

Dependency scan

Explorer payload

Deleting a field that is in use

Values

Example — define a lifetime-value field, then set it

See also