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

The examples below hit the two endpoints you’ll combine most — defining a field and writing its value on a contact — so you can copy the header shape and envelope handling once and reuse it everywhere on this page. TypeScript uses the Node SDK’s typed helpers; Go, Ruby, and PHP call the same endpoints with plain HTTP clients, so no Orbit SDK dependency is required.

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

# Set it on a contact
curl -X PUT https://api.orbit.devotel.io/api/v1/custom-fields/values \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contact_id": "cnt_9f8a7b6c", "key": "customer_tier", "value": "gold" }'

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

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

// Define the field
const definition = await orbit.customFields.create({
  name: "Customer tier",
  key: "customer_tier",
  data_type: "enum",
  enum_values: ["bronze", "silver", "gold"],
  resource: "contact",
});

// Set it on a contact — the typed SDK wraps definitions only, so the
// values write goes through the generic escape hatch
await orbit.request("PUT", "/custom-fields/values", {
  contact_id: "cnt_9f8a7b6c",
  key: "customer_tier",
  value: "gold",
});

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

from orbit_sdk import OrbitClient

client = OrbitClient.from_api_key("dv_test_sk_YOUR_KEY")

# Define the field
definition = client.request(
    "POST",
    "/custom-fields",
    json_body={
        "name": "Customer tier",
        "key": "customer_tier",
        "type": "select",
        "options": ["bronze", "silver", "gold"],
    },
)

# Set it on a contact
written = client.request(
    "PUT",
    "/custom-fields/values",
    json_body={"contact_id": "cnt_9f8a7b6c", "key": "customer_tier", "value": "gold"},
)

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	headers := func(req *http.Request) {
		req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
		req.Header.Set("Content-Type", "application/json")
	}

	// Define the field
	defineReq, _ := http.NewRequest("POST",
		"https://api.orbit.devotel.io/api/v1/custom-fields/",
		bytes.NewBuffer([]byte(`{"name": "Customer tier", "key": "customer_tier", "type": "select", "options": ["bronze", "silver", "gold"]}`)))
	headers(defineReq)
	defineRes, _ := http.DefaultClient.Do(defineReq)
	defer defineRes.Body.Close()

	// Set it on a contact
	setReq, _ := http.NewRequest("PUT",
		"https://api.orbit.devotel.io/api/v1/custom-fields/values",
		bytes.NewBuffer([]byte(`{"contact_id": "cnt_9f8a7b6c", "key": "customer_tier", "value": "gold"}`)))
	headers(setReq)
	setRes, _ := http.DefaultClient.Do(setReq)
	defer setRes.Body.Close()

	body, _ := io.ReadAll(setRes.Body)
	fmt.Println(string(body))
}

require "net/http"
require "json"
require "uri"

headers = {
  "X-API-Key" => ENV["ORBIT_API_KEY"],
  "Content-Type" => "application/json",
}

def call(klass, path, body, headers)
  uri = URI("https://api.orbit.devotel.io/api/v1/custom-fields#{path}")
  req = klass.new(uri, headers)
  req.body = JSON.generate(body)
  Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
end

# Define the field
definition = call(Net::HTTP::Post, "/", {
  name: "Customer tier",
  key: "customer_tier",
  type: "select",
  options: ["bronze", "silver", "gold"],
}, headers)
puts JSON.parse(definition.body).dig("data", "id")

# Set it on a contact
written = call(Net::HTTP::Put, "/values", {
  contact_id: "cnt_9f8a7b6c",
  key: "customer_tier",
  value: "gold",
}, headers)
puts JSON.parse(written.body).dig("data", "ok")

<?php
function callOrbit(string $method, string $path, array $body): array {
  $ch = curl_init('https://api.orbit.devotel.io/api/v1/custom-fields' . $path);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: ' . getenv('ORBIT_API_KEY'),
    'Content-Type: application/json',
  ]);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
  return json_decode(curl_exec($ch), true);
}

// Define the field
$definition = callOrbit('POST', '/', [
  'name' => 'Customer tier',
  'key' => 'customer_tier',
  'type' => 'select',
  'options' => ['bronze', 'silver', 'gold'],
]);
echo $definition['data']['id'] . "\n";

// Set it on a contact
$written = callOrbit('PUT', '/values', [
  'contact_id' => 'cnt_9f8a7b6c',
  'key' => 'customer_tier',
  'value' => 'gold',
]);
var_export($written['data']['ok']);

The Python SDK doesn’t wrap custom fields — its client.request escape hatch shown above defines the field and sets it on a contact (source-only; vendor it from packages/sdk-python). Go, Ruby, and PHP use plain HTTP clients, so they run without an Orbit SDK. 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.

Worked sequences

Everything below the Definitions table works end to end: read one field, check what’s actually stored under it, update its presentation, reorder the list, then run the dependency scan before you delete. Typescript uses the SDK’s generic orbit.request escape hatch since the typed helpers wrap definitions only; Python/Go/Ruby/PHP call the same endpoints with plain HTTP.

FIELD="cf_01J8Z9K3P4Q5R6S7T8U9V0W1X2"

# 1. List definitions
curl https://api.orbit.devotel.io/api/v1/custom-fields/ \
  -H "X-API-Key: $ORBIT_API_KEY"

# 2. Get one definition
curl https://api.orbit.devotel.io/api/v1/custom-fields/$FIELD \
  -H "X-API-Key: $ORBIT_API_KEY"

# 3. Inspect usage + PII-redacted samples
curl https://api.orbit.devotel.io/api/v1/custom-fields/$FIELD/explorer \
  -H "X-API-Key: $ORBIT_API_KEY"

# 4. Update the presentation (key + type are frozen)
curl -X PATCH https://api.orbit.devotel.io/api/v1/custom-fields/$FIELD \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Customer tier (revised)", "description": "Primary account segment." }'

# 5. Move it to the top of the dashboard list
curl -X POST https://api.orbit.devotel.io/api/v1/custom-fields/reorder \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"ordered_ids\": [\"$FIELD\"] }"

# 6. BEFORE deleting: scan what references it
DEPS=$(curl -s https://api.orbit.devotel.io/api/v1/custom-fields/$FIELD/dependencies \
  -H "X-API-Key: $ORBIT_API_KEY")
echo "$DEPS"

# 7. Delete without force → any reference returns 409 CUSTOM_FIELD_IN_USE
#    with the same dependency snapshot in the error details. Re-run with
#    ?force=true to delete anyway (field stripped from every contact;
#    dependent segments/flows flagged broken).
curl -X DELETE "https://api.orbit.devotel.io/api/v1/custom-fields/$FIELD?force=true" \
  -H "X-API-Key: $ORBIT_API_KEY"

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

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

const FIELD = "cf_01J8Z9K3P4Q5R6S7T8U9V0W1X2";

// 1. List definitions
const list = (await orbit.customFields.list()).data;

// 2. Inspect usage via the generic escape hatch
const explorer = await orbit.request(
  "GET",
  `/custom-fields/${FIELD}/explorer`,
);

// 3. Update presentation
await orbit.request("PATCH", `/custom-fields/${FIELD}`, {
  name: "Customer tier (revised)",
  description: "Primary account segment.",
});

// 4. Reorder
await orbit.request("POST", "/custom-fields/reorder", {
  ordered_ids: [FIELD],
});

// 5. Dependency scan BEFORE delete — the same snapshot a guarded
//    delete refuses with on 409 CUSTOM_FIELD_IN_USE.
const deps = await orbit.request(
  "GET",
  `/custom-fields/${FIELD}/dependencies`,
);

const total =
  deps.data.contacts_with_data +
  deps.data.segments.length +
  deps.data.campaigns.length +
  deps.data.flows.length +
  deps.data.drip_enrollments;

if (total === 0) {
  await orbit.request("DELETE", `/custom-fields/${FIELD}`);
} else {
  console.log("field in use — inspect deps before force-deleting");
}

from orbit_sdk import OrbitClient

client = OrbitClient.from_api_key("dv_test_sk_YOUR_KEY")

FIELD = "cf_01J8Z9K3P4Q5R6S7T8U9V0W1X2"

# 1. List definitions
defs = client.request("GET", "/custom-fields")

# 2. Get one definition
field = client.request("GET", f"/custom-fields/{FIELD}")

# 3. Inspect usage
explorer = client.request("GET", f"/custom-fields/{FIELD}/explorer")

# 4. Update presentation
client.request(
    "PATCH",
    f"/custom-fields/{FIELD}",
    json_body={"name": "Customer tier (revised)"},
)

# 5. Reorder
client.request("POST", "/custom-fields/reorder", json_body={"ordered_ids": [FIELD]})

# 6. Dependency scan BEFORE delete
deps = client.request("GET", f"/custom-fields/{FIELD}/dependencies")["data"]
total = (
    deps["contacts_with_data"]
    + len(deps["segments"])
    + len(deps["campaigns"])
    + len(deps["flows"])
    + deps["drip_enrollments"]
)
if total == 0:
    client.request("DELETE", f"/custom-fields/{FIELD}")

// Plain HTTP — same endpoints. Same sequence as the cURL block;
// the helper trims to the request/response pair.
func main() {
	field := "cf_01J8Z9K3P4Q5R6S7T8U9V0W1X2"

	// 1. List definitions
	callOrbit("GET", "/custom-fields/", nil)

	// 2. Get one definition
	callOrbit("GET", "/custom-fields/"+field, nil)

	// 3. Usage explorer
	callOrbit("GET", "/custom-fields/"+field+"/explorer", nil)

	// 4. Update presentation
	callOrbit("PATCH", "/custom-fields/"+field,
		[]byte(`{"name": "Customer tier (revised)"}`))

	// 5. Reorder
	callOrbit("POST", "/custom-fields/reorder",
		[]byte(`{"ordered_ids": ["`+field+`"]}`))

	// 6. Dependency scan (its `data.dependencies` block is the same
	//    snapshot a guarded delete 409s with)
	callOrbit("GET", "/custom-fields/"+field+"/dependencies", nil)

	// 7. Delete — guarded on a referenced field, so send ?force=true
	//    only after reviewing the dependencies first.
	callOrbit("DELETE", "/custom-fields/"+field+"?force=true", nil)
}

FIELD = "cf_01J8Z9K3P4Q5R6S7T8U9V0W1X2"

# 1. List definitions
call(Net::HTTP::Get, "/", nil, headers)

# 2. Get one definition
call(Net::HTTP::Get, "/#{FIELD}", nil, headers)

# 3. Usage explorer
call(Net::HTTP::Get, "/#{FIELD}/explorer", nil, headers)

# 4. Update presentation
call(Net::HTTP::Patch, "/#{FIELD}", { name: "Customer tier (revised)" }, headers)

# 5. Reorder
call(Net::HTTP::Post, "/reorder", { ordered_ids: [FIELD] }, headers)

# 6. Dependency scan BEFORE delete
deps = call(Net::HTTP::Get, "/#{FIELD}/dependencies", nil, headers)
parsed = JSON.parse(deps.body)["data"]
total = parsed["contacts_with_data"] + parsed["segments"].length +
        parsed["campaigns"].length + parsed["flows"].length +
        parsed["drip_enrollments"]

if total.zero?
  # A field with zero dependents deletes cleanly, no force needed.
  call(Net::HTTP::Delete, "/#{FIELD}", nil, headers)
else
  # Otherwise a bare DELETE 409s with CUSTOM_FIELD_IN_USE and the same
  # snapshot — review the deps before appending ?force=true.
  puts JSON.generate(parsed)
end

$FIELD = 'cf_01J8Z9K3P4Q5R6S7T8U9V0W1X2';

// 1. List definitions
$list = callOrbit('GET', '/', []);

// 2. Get one definition
$field = callOrbit('GET', '/' . $FIELD, []);

// 3. Usage explorer
$explorer = callOrbit('GET', '/' . $FIELD . '/explorer', []);

// 4. Update presentation
callOrbit('PATCH', '/' . $FIELD, ['name' => 'Customer tier (revised)']);

// 5. Reorder
callOrbit('POST', '/reorder', ['ordered_ids' => [$FIELD]]);

// 6. Dependency scan BEFORE delete
$deps = callOrbit('GET', '/' . $FIELD . '/dependencies', [])['data'];
$total = $deps['contacts_with_data']
  + count($deps['segments'])
  + count($deps['campaigns'])
  + count($deps['flows'])
  + $deps['drip_enrollments'];

if ($total === 0) {
  // Zero dependents → a clean delete with no force flag.
  callOrbit('DELETE', '/' . $FIELD, []);
} else {
  echo json_encode($deps); // Review before appending ?force=true.
}

Step 6–7 above models the safeguard the prose describes under Deleting a field that is in use: call dependencies first, and if any total is non-zero a plain DELETE returns 409 CUSTOM_FIELD_IN_USE carrying the same dependency snapshot in error.details.dependencies. Reissue the delete with ?force=true only after you’ve confirmed the listed segments, campaigns, flows, and contacts can survive losing the field.

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 }'

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

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

// 1. Define
await orbit.customFields.create({
  key: "ltv_usd",
  data_type: "number",
  name: "Lifetime value (USD)",
  resource: "contact",
});

// 2. Set on a contact — values write goes through the generic escape hatch
await orbit.request("PUT", "/custom-fields/values", {
  contact_id: "cnt_abc123",
  key: "ltv_usd",
  value: 482.5,
});

API Reference

All Endpoints

Custom Fields API: typed contact metadata

Custom Fields API

Using the SDKs

Definitions

Worked sequences

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

​Worked sequences

​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

Worked sequences

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