Contacts orientation: worked examples with full response bodies

The contact resource

A contact is one record in your directory — phone, email, name, tags, consent, plus your own data layered on top. Custom-field values ride on the contact as the custom_fields object: set them on a contact and they come back inline on every contact response — create, read, list — with no separate lookup. Custom-field keys and their types are defined under /api/v1/custom-fields. Write a value with PUT /api/v1/custom-fields/values and read it back on the contact’s custom_fields object. Every response on this page follows the same envelope — data plus a meta block carrying request_id, timestamp, and, on list responses, pagination — so the examples below hold for every endpoint here. Errors follow Devotel Orbit’s { error, meta } envelope, shown once under Error envelope.

Worked sequence: create, set custom fields, read back

The run-through every integration does first: create the contact, attach your own data, then pull the contact back and see the values inline.

1. Create the contact

POST /api/v1/contacts/

At least one of phone or email is required. Send phone numbers in E.164 (+14155551234); display formats are normalized to E.164 before insert. Request

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/contacts/" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+14155551234",
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "tags": [
    "vip"
  ]
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/contacts/', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "phone": "+14155551234",
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "tags": [
    "vip"
  ]
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/contacts/", headers=headers, json={
  "phone": "+14155551234",
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "tags": [
    "vip"
  ]
})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/contacts/", bytes.NewBuffer([]byte(`{
  "phone": "+14155551234",
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "tags": [
    "vip"
  ]
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/contacts/')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "phone": "+14155551234",
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "tags": [
    "vip"
  ]
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/contacts/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "phone": "+14155551234",
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "tags": [
    "vip"
  ]
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "id": "ct_1a2b3c4d5e6f7081",
    "phone": "+14155551234",
    "email": "ada@example.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "full_name": "Ada Lovelace",
    "country_code": null,
    "timezone": null,
    "locale": null,
    "custom_fields": {},
    "tags": ["vip"],
    "consent": null,
    "last_activity_at": null,
    "created_at": "2026-08-24T09:15:00.000Z",
    "updated_at": "2026-08-24T09:15:00.000Z"
  },
  "meta": {
    "request_id": "req_create",
    "timestamp": "2026-08-24T09:15:00.000Z"
  }
}

The new contact returns an empty custom_fields object until you set values.

2. Set custom-field values

PUT /api/v1/custom-fields/values

One call per field. key must match a custom-field definition you already created, and the value must match that definition’s type — values of the wrong type are rejected. Request

cURL

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": "ct_1a2b3c4d5e6f7081",
  "key": "plan",
  "value": "pro"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/custom-fields/values', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "contact_id": "ct_1a2b3c4d5e6f7081",
  "key": "plan",
  "value": "pro"
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.put("https://api.orbit.devotel.io/api/v1/custom-fields/values", headers=headers, json={
  "contact_id": "ct_1a2b3c4d5e6f7081",
  "key": "plan",
  "value": "pro"
})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("PUT", "https://api.orbit.devotel.io/api/v1/custom-fields/values", bytes.NewBuffer([]byte(`{
  "contact_id": "ct_1a2b3c4d5e6f7081",
  "key": "plan",
  "value": "pro"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/custom-fields/values')
req = Net::HTTP::Put.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "contact_id": "ct_1a2b3c4d5e6f7081",
  "key": "plan",
  "value": "pro"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/custom-fields/values');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "contact_id": "ct_1a2b3c4d5e6f7081",
  "key": "plan",
  "value": "pro"
}
JSON);
echo curl_exec($ch);

{
  "data": { "updated": true },
  "meta": {
    "request_id": "req_set_value",
    "timestamp": "2026-08-24T09:16:00.000Z"
  }
}

3. Read back — values inline

GET /api/v1/contacts/{id}

Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/contacts/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/contacts/{id}', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/contacts/{id}", headers=headers)
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/contacts/{id}", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/contacts/{id}')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/contacts/{id}');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "id": "ct_1a2b3c4d5e6f7081",
    "phone": "+14155551234",
    "email": "ada@example.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "full_name": "Ada Lovelace",
    "country_code": null,
    "timezone": null,
    "locale": null,
    "custom_fields": {
      "plan": "pro"
    },
    "tags": ["vip"],
    "consent": null,
    "last_activity_at": null,
    "created_at": "2026-08-24T09:15:00.000Z",
    "updated_at": "2026-08-24T09:16:00.000Z"
  },
  "meta": {
    "request_id": "req_get",
    "timestamp": "2026-08-24T09:17:00.000Z"
  }
}

Worked sequence: list with filters, then paginate

GET /api/v1/contacts/

Filters combine on the query string — tags=vip, country_code=US — search narrows by name, phone, or email. The response is cursor-paginated: while meta.pagination.has_more is true, pass meta.pagination.cursor back as the cursor query parameter to fetch the next page. Here the list is filtered to one tag. Request

curl -X GET "https://api.orbit.devotel.io/api/v1/contacts/?tags=vip&limit=2" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": [
    {
      "id": "ct_1a2b3c4d5e6f7081",
      "phone": "+14155551234",
      "email": "ada@example.com",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "full_name": "Ada Lovelace",
      "custom_fields": { "plan": "pro" },
      "tags": ["vip"],
      "created_at": "2026-08-24T09:15:00.000Z",
      "updated_at": "2026-08-24T09:16:00.000Z"
    },
    {
      "id": "ct_2b3c4d5e6f70819a",
      "phone": "+442071234567",
      "email": "grace@example.com",
      "first_name": "Grace",
      "last_name": "Hopper",
      "full_name": "Grace Hopper",
      "custom_fields": {},
      "tags": ["vip"],
      "created_at": "2026-08-24T10:02:00.000Z",
      "updated_at": "2026-08-24T10:02:00.000Z"
    }
  ],
  "meta": {
    "request_id": "req_list",
    "timestamp": "2026-08-24T10:05:00.000Z",
    "pagination": {
      "cursor": "eyJsYXN0X2lkIjoiY3RfMmIzYzRkNWU2ZjcwODE5YSJ9",
      "has_more": true,
      "total": null
    }
  }
}

has_more is true, so request the next page:

curl -X GET "https://api.orbit.devotel.io/api/v1/contacts/?tags=vip&limit=2&cursor=eyJsYXN0X2lkIjoiY3RfMmIzYzRkNWU2ZjcwODE5YSJ9" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Treat the cursor as opaque. Keep the same filters across pages and stop when has_more comes back false.

Error envelope

Validation failures return 422 with a VALIDATION_ERROR code. The classic case is a phone value that fails the format and length checks — below the E.164 floor or not recognizable:

422

{
  "error": {
    "code": "VALIDATION_ERROR",
    "status": 422,
    "message": "phone: must be a valid phone number in international format"
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-08-24T09:15:00.000Z"
  }
}

When you hit this on create or update, normalize the number to E.164 (country code, digits only, leading +) and retry. A missing-or-unknown custom-field key on PUT /custom-fields/values surfaces the same envelope with a four-hundred status, so handle both before you code a special case. Erasure is a tenant-owned control: you file it, Orbit executes it and keeps the audit chain. The generated reference section for DELETE /api/v1/contacts/{id}/gdpr/delete documents the synchronous cascade but stops at 204 No Content — nothing there tells you how to confirm the deletion you just ran, or how to read the pending/completed status on the cancellable flow. This section closes that gap.

The immediate delete answers 204; the status lives one call away

DELETE /api/v1/contacts/{id}/gdpr/delete

The immediate right-to-erasure returns 204 with an intentionally empty body. On success the contact is gone — any read of the same id returns 404. The probe pair: mint the re-auth challenge, delete, then confirm. Step 1 — mint the re-auth challenge

curl -X POST "https://api.orbit.devotel.io/api/v1/contacts/ct_1a2b3c4d5e6f7081/gdpr/delete/challenge" \
  -H "X-API-Key: dv_live_sk_your_key_here"

200

{
  "data": {
    "challenge_token": "reauth_4d5e6f7081a2b3c4d5e6f7081a2b3c4d",
    "expires_at": "2026-08-24T09:20:00.000Z"
  },
  "meta": {
    "request_id": "req_challenge",
    "timestamp": "2026-08-24T09:15:00.000Z"
  }
}

Step 2 — delete (204, empty body by design)

curl -X DELETE "https://api.orbit.devotel.io/api/v1/contacts/ct_1a2b3c4d5e6f7081/gdpr/delete" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "X-Reauth-Challenge: reauth_4d5e6f7081a2b3c4d5e6f7081a2b3c4d"

Without a valid challenge token in X-Reauth-Challenge, the delete returns 401 and erases nothing:

401 Error

{
  "error": {
    "code": "REAUTH_REQUIRED",
    "status": 401,
    "message": "Fresh re-authentication is required for GDPR deletion. POST /:id/gdpr/delete/challenge first, then retry within 5 minutes with X-Reauth-Challenge header."
  },
  "meta": {
    "request_id": "req_bad",
    "timestamp": "2026-08-24T09:15:01.000Z"
  }
}

The cancellable erasure request returns a full status envelope

POST /api/v1/contacts/{id}/gdpr/erasure-request

Unlike the immediate cascade, this flow starts a cooling-off window (per-tenant, seven days by default) and answers 202 with the full request — so you always know whether the deletion is still pending, executing, completed, or cancellable:

{
  "data": {
    "id": "req_3c4d5e6f7081a2b3c4d5e6",
    "contact_id": "ct_1a2b3c4d5e6f7081",
    "requested_by_user_id": "usr_9e8f7c6b5a49",
    "status": "pending",
    "requested_at": "2026-08-24T09:15:00.000Z",
    "cooling_off_ends_at": "2026-08-31T09:15:00.000Z",
    "executed_at": null,
    "cancelled_at": null,
    "failure_reason": null,
    "attempt_count": 0,
    "created_at": "2026-08-24T09:15:00.000Z",
    "updated_at": "2026-08-24T09:15:00.000Z"
  },
  "meta": {
    "request_id": "req_file",
    "timestamp": "2026-08-24T09:15:00.000Z"
  }
}

status moves pending → executing → executed once the scheduled worker hard-deletes the contact past cooling_off_ends_at (a failed run leaves failure_reason and retries up to its attempt cap; a cancelled request records cancelled_at and never executes). To cancel while it is still pending, pass the request id to POST /:id/gdpr/erasure-request/:requestId/cancel. Poll the status on the per-contact list endpoint — the object above under data.items:

curl -X GET "https://api.orbit.devotel.io/api/v1/contacts/ct_1a2b3c4d5e6f7081/gdpr/erasure-requests" \
  -H "X-API-Key: dv_live_sk_your_key_here"

200

{
  "data": {
    "items": [
      {
        "id": "req_3c4d5e6f7081a2b3c4d5e6",
        "contact_id": "ct_1a2b3c4d5e6f7081",
        "status": "executed",
        "requested_at": "2026-08-24T09:15:00.000Z",
        "cooling_off_ends_at": "2026-08-31T09:15:00.000Z",
        "executed_at": "2026-08-31T09:15:02.000Z",
        "cancelled_at": null,
        "failure_reason": null,
        "attempt_count": 1,
        "created_at": "2026-08-24T09:15:00.000Z",
        "updated_at": "2026-08-31T09:15:02.000Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_status",
    "timestamp": "2026-08-31T09:15:03.000Z"
  }
}

Duplicate detection and merge review

Two endpoints handle duplicate detection: a cheap aggregate count for banner surfaces and pre-merge checks, and the full group list you fetch when you open the merge workflow.

GET /api/v1/contacts/duplicates/count

Returns extras — the number of contacts that would be merged away — plus hasMore indicating whether duplicates exist beyond the slice the count scanned. Use it for banner headlines and pre-merge checks.

string

exact (default) or fuzzy. exact is the right choice for banner counts; fuzzy mirrors the detection pass the merge endpoint uses.

integer

Per-strategy group cap, default 100, range 1–200. Raise it when hasMore returns true and you need to scan deeper before reporting “0 duplicates.”

Use GET /duplicates to fetch the full group list (with per-group contact records) when you actually render the merge review UI — fetching it just for a banner paints the contacts page with data you don’t read.

API Reference

All Endpoints

Contacts orientation: worked examples with full response bodies

The contact resource

Worked sequence: create, set custom fields, read back

1. Create the contact

2. Set custom-field values

3. Read back — values inline

Worked sequence: list with filters, then paginate

Error envelope

The immediate delete answers 204; the status lives one call away

The cancellable erasure request returns a full status envelope

Duplicate detection and merge review

​The contact resource

​Worked sequence: create, set custom fields, read back

​1. Create the contact

​2. Set custom-field values

​3. Read back — values inline

​Worked sequence: list with filters, then paginate

​Error envelope

​GDPR erasure — from request to confirmed status

​The immediate delete answers 204; the status lives one call away

​The cancellable erasure request returns a full status envelope

​Duplicate detection and merge review

The contact resource

Worked sequence: create, set custom fields, read back

1. Create the contact

2. Set custom-field values

3. Read back — values inline

Worked sequence: list with filters, then paginate

Error envelope

GDPR erasure — from request to confirmed status

The immediate delete answers 204; the status lives one call away

The cancellable erasure request returns a full status envelope

Duplicate detection and merge review