Worked request and response samples

Access note for the BigQuery reverse-ETL config endpoints — GET /api/v1/cdp/reverse-etl and PATCH /api/v1/cdp/reverse-etl accept the developer role in addition to owner / admin. The generated per-operation descriptions below may still say “Owner / admin only” because they aren’t annotated in the route schema yet; this overlay is the authoritative source until they are.

Copy a request body as written, substitute your own ids, and compare the response envelope. Errors follow Devotel Orbit’s { error, meta } envelope, shown once below under Error envelope.

Resolve an identity

GET /api/v1/cdp/identity-resolution/rules

Returns the identity-resolution rules that map the inputs you provide (anonymous_id, email, phone, user_id) onto a single profile. Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/cdp/identity-resolution/rules" \
  -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/cdp/identity-resolution/rules', {
  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/cdp/identity-resolution/rules", 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/cdp/identity-resolution/rules", 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/cdp/identity-resolution/rules')
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/cdp/identity-resolution/rules');
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": [
    {
      "rule": "email",
      "priority": 10,
      "match": "exact"
    }
  ],
  "meta": {
    "request_id": "req_cdp_rules",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

Get a profile’s resolved traits by email

GET /api/v1/cdp/profiles/by-email/{email}/traits

Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/cdp/profiles/by-email/{email}/traits" \
  -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/cdp/profiles/by-email/{email}/traits', {
  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/cdp/profiles/by-email/{email}/traits", 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/cdp/profiles/by-email/{email}/traits", 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/cdp/profiles/by-email/{email}/traits')
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/cdp/profiles/by-email/{email}/traits');
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": {
    "first_name": "Jane",
    "company": "Acme Inc"
  },
  "meta": {
    "request_id": "req_cdp_traits",
    "timestamp": "2026-08-01T12:01:00.000Z"
  }
}

Error envelope

422

{
  "error": {
    "code": "VALIDATION_ERROR",
    "status": 422,
    "message": "email: Required"
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

Compute a conversion-lift report for an audience activation

POST /api/v1/cdp/audience/activations/{id}/lift

Record per-arm conversions for one activation run and compute its incrementality report. Configure a holdout percent on the destination (Audience → Activation in the dashboard) and Orbit carves a randomized control group that is never uploaded; the endpoint then compares the exposed (treatment) arm against the unexposed (control) arm. Body: treatment_converted and control_converted (integers, joined from your analytics or warehouse), plus an optional confidence_level (default 0.95). Response carries each arm’s size and conversion rate, absolute and relative lift, the confidence interval, z-score, p-value, and an is_significant flag. A run with no holdout returns tracking_method: "no_holdout". Owner / admin / developer only.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/cdp/audience/activations/act_123/lift" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "treatment_converted": 320,
  "control_converted": 610
}'

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/cdp/audience/activations/act_123/lift', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "treatment_converted": 320,
  "control_converted": 610
}),
})
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/cdp/audience/activations/act_123/lift", headers=headers, json={
  "treatment_converted": 320,
  "control_converted": 610
})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/cdp/audience/activations/act_123/lift", bytes.NewBuffer([]byte(`{
  "treatment_converted": 320,
  "control_converted": 610
}`)))
	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/cdp/audience/activations/act_123/lift')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "treatment_converted": 320,
  "control_converted": 610
}.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/cdp/audience/activations/act_123/lift');
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
{
  "treatment_converted": 320,
  "control_converted": 610
}
JSON);
echo curl_exec($ch);

Ingest operations use HMAC signing, not X-API-Key

The seven POST /cdp/v1/{ingest_id}/* operations below — track, identify, page, screen, group, alias, batch — still carry an X-API-Key header in the generated request examples. That header is wrong on this surface: the ingest gateway accepts only x-orbit-cdp-signature, x-orbit-cdp-timestamp, and x-orbit-cdp-nonce, and rejects Clerk sessions and API keys. Substitute your ingest id from the CDP source config for {ingest_id}, and compute the signature yourself — copy-pasting a signed curl never works, since the signature changes with every edit to the body:

Take the exact JSON you will send; the HMAC covers those raw bytes.
Sign <timestamp>.<nonce>.<raw body> with your workspace ingest secret (mint one via POST /api/v1/cdp/secrets); prefix the hex digest with v1=.
Send the result as x-orbit-cdp-signature, x-orbit-cdp-timestamp, x-orbit-cdp-nonce on one of the seven operations.

The full wire contract and runnable signing loops in Node, Python, and Go live in the CDP ingest signing guide. The worked sample for track further up this section shows the complete call — headers, body, ack — end to end.

Tracking-plan violations return 422 with a per-field diff

With strict enforcement, a non-conforming payload returns HTTP 422 with a structured reason you (or your producer logs) can act on. The rejected messageId is never consumed, so a corrected retry is accepted cleanly.

{
  "error": {
    "code": "TRACKING_PLAN_VIOLATION",
    "status": 422,
    "message": "Event rejected by tracking plan (enforcement=strict). See `details.violations` for the mismatch list.",
    "details": {
      "event_name": "signed_up",
      "violations": [
        {
          "type": "extra_property",
          "path": "properties.referrer",
          "expected": "absent",
          "actual": "organic"
        }
      ]
    }
  },
  "meta": {
    "request_id": "req_7xKqT3",
    "timestamp": "2026-08-26T12:00:41.000Z"
  }
}

Author violations you want enforced in your workspace’s tracking plan; until then violations log without rejects. When a strict-mode rejection lands, the TRACKING_PLAN_VIOLATION runbook decodes the fired rule and the fix paths.

Get one account’s score detail

GET /api/v1/cdp/accounts/score — substitute your company name into the account query parameter

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/cdp/accounts/score?account=Globex%20Corporation" \
  -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/cdp/accounts/score?account=Globex%20Corporation', {
  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/cdp/accounts/score?account=Globex%20Corporation", 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/cdp/accounts/score?account=Globex%20Corporation", 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/cdp/accounts/score?account=Globex%20Corporation')
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/cdp/accounts/score?account=Globex%20Corporation');
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);

The response carries the account-wide rollup plus a member breakdown — each contact’s individual churn, intent, propensity, LTV, and lifecycle stage — so a CSM can see WHICH contacts drive the account’s risk.

{
  "data": {
    "account": "Globex Corporation",
    "contact_count": 42,
    "firmographic_band": "mid",
    "firmographic_domain": "globex.com",
    "firmographic_identity_source": "enrichment",
    "firmographic_enriched": true,
    "account_churn_risk": 0.31,
    "max_contact_churn_risk": 0.78,
    "expansion_propensity": 0.64,
    "intent_score": 0.55,
    "total_value_cents": 4820000,
    "health_segment": "expansion",
    "members_returned": 2,
    "members": [
      {
        "contact_id": "cnt_1f3a9b2c4d5e60718293a4b5c6",
        "display_name": "Jane Doe",
        "churn_risk": 0.72,
        "intent_score": 0.4,
        "propensity_score": 0.66,
        "ltv_estimate_cents": 250000,
        "segment_label": "champion",
        "lifecycle_stage": "customer"
      },
      {
        "contact_id": "cnt_9b7c6d5e4f3a2b1c0d9e8f7a6",
        "display_name": "Sam Ortiz",
        "churn_risk": 0.18,
        "intent_score": 0.32,
        "propensity_score": 0.91,
        "ltv_estimate_cents": 250000,
        "segment_label": "advocate",
        "lifecycle_stage": "customer"
      }
    ]
  },
  "meta": {
    "request_id": "req_cdp_acct_score",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Track an event (Segment-compatible ingest)

POST /cdp/v1/{ingest_id}/track — the ingest endpoint lives outside /api/v1; sign the raw body with your tenant ingest secret

{ingest_id} comes from the CDP source config page; sign the raw request body with the tenant ingest secret as the four x-orbit-cdp-* headers. Drop the template userId or anonymousId in exactly as shown, fill the event name you want to log, and the response ack ties the event back to the contact it resolved to.

cURL

curl -X POST "https://api.orbit.devotel.io/cdp/v1/ing_7f2c9a1b3d4e5f60718293a4/track" \
  -H "Content-Type: application/json" \
  -H "x-orbit-cdp-signature: <hmac-of-raw-body>" \
  -H "x-orbit-cdp-timestamp: <unix-seconds>" \
  -H "x-orbit-cdp-nonce: <unique-per-request>" \
  -d '{
  "userId": "user_981735",
  "anonymousId": "anon_3f6a81c2d4e5471a9b0c2d5e",
  "event": "signed_up",
  "properties": { "plan": "pro", "referrer": "organic" },
  "timestamp": "2026-08-26T12:00:00.000Z"
}'

Node.js

const body = {
  userId: 'user_981735',
  anonymousId: 'anon_3f6a81c2d4e5471a9b0c2d5e',
  event: 'signed_up',
  properties: { plan: 'pro', referrer: 'organic' },
  timestamp: '2026-08-26T12:00:00.000Z',
}
const raw = JSON.stringify(body)
const signature = hmacSha256Hex(raw, process.env.ORBIT_CDP_INGEST_SECRET!)
const res = await fetch(
  'https://api.orbit.devotel.io/cdp/v1/ing_7f2c9a1b3d4e5f60718293a4/track',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-orbit-cdp-signature': signature,
      'x-orbit-cdp-timestamp': String(Math.floor(Date.now() / 1000)),
      'x-orbit-cdp-nonce': `nonce_${crypto.randomUUID()}`,
    },
    body: raw,
  }
)
console.log(await res.json())

The 200 ack is the same shape for every ingest path (track, identify, group, screen, page, alias, batch). contact_id is null when the payload didn’t resolve to a contact yet (anonymous id awaits an identify) and deduped flips true when a previously accepted event with the same message id is replayed.

{
  "data": {
    "received": true,
    "event_id": "evt_01J8Z9K3P4Q5R6S7T8U9V0W1X2",
    "deduped": false,
    "contact_id": "cnt_1f3a9b2c4d5e60718293a4b5c6"
  },
  "meta": {
    "request_id": "req_86qGvH2",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Identify a user and bind traits

POST /cdp/v1/{ingest_id}/identify

Supply at least one of userId or anonymousId plus the traits you want to attach. The same contact_id you got back from the track call is returned after the identity is bound.

cURL

curl -X POST "https://api.orbit.devotel.io/cdp/v1/ing_7f2c9a1b3d4e5f60718293a4/identify" \
  -H "Content-Type: application/json" \
  -H "x-orbit-cdp-signature: <hmac-of-raw-body>" \
  -H "x-orbit-cdp-timestamp: <unix-seconds>" \
  -H "x-orbit-cdp-nonce: <unique-per-request>" \
  -d '{
  "userId": "user_981735",
  "anonymousId": "anon_3f6a81c2d4e5471a9b0c2d5e",
  "traits": { "email": "jane@globex.com", "first_name": "Jane", "plan": "pro" }
}'

{
  "data": {
    "received": true,
    "event_id": "evt_01J8Z9K3P4Q5R6S7T8U9V0W1X3",
    "deduped": false,
    "contact_id": "cnt_1f3a9b2c4d5e60718293a4b5c6"
  },
  "meta": {
    "request_id": "req_71mPzK4",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Ingest events in a batch with an `alias` bridge

POST /cdp/v1/{ingest_id}/batch and POST /cdp/v1/{ingest_id}/alias

Batch accepts a batch array of events (track / identify / group / page / screen); each element triggers its own resolve. alias ties an anonymousId to a userId — send it before the user actually signed in so the fan-out attached browsing history to the account.

cURL

curl -X POST "https://api.orbit.devotel.io/cdp/v1/ing_7f2c9a1b3d4e5f60718293a4/batch" \
  -H "Content-Type: application/json" \
  -H "x-orbit-cdp-signature: <hmac-of-raw-body>" \
  -H "x-orbit-cdp-timestamp: <unix-seconds>" \
  -H "x-orbit-cdp-nonce: <unique-per-request>" \
  -d '{
  "batch": [
    { "type": "track", "event": "checkout_started", "anonymousId": "anon_3f6a81c2d4e5471a9b0c2d5e" },
    { "type": "identify", "userId": "user_981735", "traits": { "email": "jane@globex.com" } }
  ]
}'

{
  "data": {
    "received": true,
    "event_id": "evt_01J8Z9K3P4Q5R6S7T8U9V0W1X8",
    "deduped": false,
    "contact_id": null
  },
  "meta": {
    "request_id": "req_2pLqZ6",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Get a profile’s segments plus recent history

GET /api/v1/cdp/profiles/by-user-id/{user_id}/segments and GET /api/v1/cdp/profiles/by-user-id/{user_id}/events

Both read surfaces resolve the same identity to the same contact_id; from there, segments returns the membership set (event- or realtime-sourced) and events returns the newest-N activity for the visible timeline.

{
  "data": {
    "user_id": "user_981735",
    "contact_id": "cnt_1f3a9b2c4d5e60718293a4b5c6",
    "segments": [
      {
        "segment_id": "seg_7c4e2a9b1d3f50618293a4b5",
        "segment_name": "High-value experiment group",
        "joined_at": "2026-08-20T09:14:00.000Z",
        "source": "realtime"
      },
      {
        "segment_id": "seg_2f8b4c6d8e1a3b5c7d9e1f2a",
        "segment_name": "New customers (30d)",
        "joined_at": "2026-08-13T18:45:00.000Z",
        "source": "event"
      }
    ],
    "count": 2,
    "next_cursor": null
  },
  "meta": {
    "request_id": "req_cdp_segments",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

{
  "data": {
    "user_id": "user_981735",
    "contact_id": "cnt_1f3a9b2c4d5e60718293a4b5c6",
    "data": [
      {
        "id": "evt_01J8Z9K3P4Q5R6S7T8U9V0W1X2",
        "type": "track",
        "event_name": "order_completed",
        "received_at": "2026-08-26T11:59:56.000Z",
        "properties": { "order_id": "ord_2026_8842", "value_cents": 15400 }
      }
    ],
    "count": 1,
    "next_cursor": null
  },
  "meta": {
    "request_id": "req_cdp_events",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

List the live event stream with filters

GET /api/v1/cdp/events/debug — the live event-tail surface; filter on type, event_name, user_id, or a substring q to narrow

The endpoint returns the raw event log and accepts after/before cursors to poll. next_cursor is what you pass back as after to live- tail the stream from this point.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/cdp/events/debug?event_name=order_completed&limit=5&q=globex" \
  -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/cdp/events/debug?event_name=order_completed&limit=5&q=globex', {
  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/cdp/events/debug?event_name=order_completed&limit=5&q=globex", 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/cdp/events/debug?event_name=order_completed&limit=5&q=globex", 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/cdp/events/debug?event_name=order_completed&limit=5&q=globex')
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/cdp/events/debug?event_name=order_completed&limit=5&q=globex');
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": {
    "data": [
      {
        "id": "evt_01J8Z9K3P4Q5R6S7T8U9V0W1X2",
        "type": "track",
        "event_name": "order_completed",
        "contact_id": "cnt_1f3a9b2c4d5e60718293a4b5c6",
        "user_id": "user_981735",
        "anonymous_id": "anon_3f6a81c2d4e5471a9b0c2d5e",
        "properties": { "order_id": "ord_2026_8842", "value_cents": 15400 },
        "received_at": "2026-08-26T11:59:56.000Z"
      }
    ],
    "next_cursor": "eyJyZWNlaXZlZF9hdCI6IjIwMjYtMDgtMjZUMTE6NTk6NTYuMDAwWiIsImlkIjoiZXZ0XzAxSjhaOUszUDRRNlM3VDhVOVYwVzFYMk55In0",
    "prev_cursor": null
  },
  "meta": {
    "request_id": "req_cdp_debug",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Worked sequences for the CDP surface past the first 15 operations

By the page contract, operations past the first 15 render in cURL and TypeScript only. The five sequences below fill the gap for the calls an integration reaches next — they cover those trimmed operations in the full six-language matrix (bash, typescript, python, go, ruby, php) per the SDK language policy. Copy a request, substitute your own ids, and compare the envelope; ids use the same seg_ / cnt_ / evt_ prefixes as the tracking-plan and erasure-propagation guides.

1. Identify a profile from a server (signed ingest)

POST /cdp/v1/{ingest_id}/identify — HMAC-signed; no API key accepted on this surface. Owner of any SDK client can call it.

A server-side script or job identifies one profile at a time through the same ingest gateway the SDK flush loop uses — supply at least one of userId or anonymousId plus the traits to attach. The 200 ack echoes the contact_id the identity resolved to; the same call in a batch envelope sits above under Ingest events in a batch. Request

cURL

curl -X POST "https://api.orbit.devotel.io/cdp/v1/ing_7f2c9a1b3d4e5f60718293a4/identify" \
  -H "Content-Type: application/json" \
  -H "x-orbit-cdp-signature: <hmac-of-raw-body>" \
  -H "x-orbit-cdp-timestamp: <unix-seconds>" \
  -H "x-orbit-cdp-nonce: <unique-per-request>" \
  -d '{
  "userId": "user_981735",
  "traits": { "email": "jane@globex.com", "plan": "pro", "lifecycle_stage": "customer" }
}'

Node.js

import { createHmac } from 'node:crypto'

const body = {
  userId: 'user_981735',
  traits: { email: 'jane@globex.com', plan: 'pro', lifecycle_stage: 'customer' },
}
const raw = JSON.stringify(body)
const timestamp = String(Math.floor(Date.now() / 1000))
const nonce = `nonce_${crypto.randomUUID()}`
const signature = 'v1=' + createHmac('sha256', process.env.ORBIT_CDP_INGEST_SECRET!)
  .update(`${timestamp}.${nonce}.${raw}`)
  .digest('hex')

const res = await fetch(
  'https://api.orbit.devotel.io/cdp/v1/ing_7f2c9a1b3d4e5f60718293a4/identify',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-orbit-cdp-signature': signature,
      'x-orbit-cdp-timestamp': timestamp,
      'x-orbit-cdp-nonce': nonce,
    },
    body: raw,
  },
)
console.log(await res.json())

Python

import hashlib, hmac, json, os, time, uuid

body = {
  "userId": "user_981735",
  "traits": {"email": "jane@globex.com", "plan": "pro", "lifecycle_stage": "customer"},
}
raw = json.dumps(body).encode()
timestamp = str(int(time.time()))
nonce = "nonce_" + str(uuid.uuid4())
secret = os.environ["ORBIT_CDP_INGEST_SECRET"].encode()
digest = hmac.new(secret, timestamp.encode() + b"." + nonce.encode() + b"." + raw, hashlib.sha256)

headers = {
  "Content-Type": "application/json",
  "x-orbit-cdp-signature": "v1=" + digest.hexdigest(),
  "x-orbit-cdp-timestamp": timestamp,
  "x-orbit-cdp-nonce": nonce,
}
r = requests.post(
  "https://api.orbit.devotel.io/cdp/v1/ing_7f2c9a1b3d4e5f60718293a4/identify",
  headers=headers,
  data=raw,
)
print(r.json())

package main

import (
	"bytes"
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"net/http"
	"os"
	"strconv"
	"time"
)

func main() {
	raw := []byte(`{"userId":"user_981735","traits":{"email":"jane@globex.com","plan":"pro","lifecycle_stage":"customer"}}`)
	timestamp := strconv.FormatInt(time.Now().Unix(), 10)
	nonce := "nonce_" + hex.EncodeToString(hmac.New(sha256.New, []byte("seed")).Sum(raw)[:16])
	mac := hmac.New(sha256.New, []byte(os.Getenv("ORBIT_CDP_INGEST_SECRET")))
	mac.Write([]byte(timestamp + "." + nonce + "."))
	mac.Write(raw)
	signature := "v1=" + hex.EncodeToString(mac.Sum(nil))

	req, _ := http.NewRequest("POST",
		"https://api.orbit.devotel.io/cdp/v1/ing_7f2c9a1b3d4e5f60718293a4/identify",
		bytes.NewBuffer(raw))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("x-orbit-cdp-signature", signature)
	req.Header.Set("x-orbit-cdp-timestamp", timestamp)
	req.Header.Set("x-orbit-cdp-nonce", nonce)
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'
require 'openssl'
require 'securerandom'

body = {
  userId: 'user_981735',
  traits: { email: 'jane@globex.com', plan: 'pro', lifecycle_stage: 'customer' },
}
raw = body.to_json
timestamp = Time.now.to_i.to_s
nonce = "nonce_#{SecureRandom.uuid}"
payload = [timestamp, nonce, raw].join('.')
signature = 'v1=' + OpenSSL::HMAC.hexdigest(
  'sha256', ENV['ORBIT_CDP_INGEST_SECRET'], payload)

uri = URI('https://api.orbit.devotel.io/cdp/v1/ing_7f2c9a1b3d4e5f60718293a4/identify')
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/json'
req['x-orbit-cdp-signature'] = signature
req['x-orbit-cdp-timestamp'] = timestamp
req['x-orbit-cdp-nonce'] = nonce
req.body = raw

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

PHP

<?php
$body = '{"userId":"user_981735","traits":{"email":"jane@globex.com","plan":"pro","lifecycle_stage":"customer"}}';
$timestamp = (string) time();
$nonce = 'nonce_' . bin2hex(random_bytes(8));
$signature = 'v1=' . hash_hmac('sha256', "$timestamp.$nonce.$body", getenv('ORBIT_CDP_INGEST_SECRET'));

$ch = curl_init('https://api.orbit.devotel.io/cdp/v1/ing_7f2c9a1b3d4e5f60718293a4/identify');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Content-Type: application/json',
  'x-orbit-cdp-signature: ' . $signature,
  'x-orbit-cdp-timestamp: ' . $timestamp,
  'x-orbit-cdp-nonce: ' . $nonce,
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
echo curl_exec($ch);

The ack is the standard ingest envelope — contact_id is non-null as soon as the userId resolves against an existing contact.

{
  "data": {
    "received": true,
    "event_id": "evt_01J8Z9K3P4Q5R6S7T8U9V0W1X3",
    "deduped": false,
    "contact_id": "cnt_1f3a9b2c4d5e60718293a4b5c6"
  },
  "meta": {
    "request_id": "req_cdp_identify",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

2. Page through a segment’s members

GET /api/v1/contacts/segments/{id}/members?limit=…&cursor=… — reads the last-materialised membership snapshot; requires contacts:read.

Membership lives under Contacts (contact_segments), not the CDP ingest path — this is the same read the dashboard’s segment member view makes. Keep the returned next_cursor and pass it back as cursor until the page comes back empty; call POST /api/v1/contacts/segments/{id}/refresh first if you need the very latest audience. Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/contacts/segments/seg_7c4e2a9b1d3f50618293a4b5/members?limit=50" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

const res = await fetch(
  'https://api.orbit.devotel.io/api/v1/contacts/segments/seg_7c4e2a9b1d3f50618293a4b5/members?limit=50',
  {
    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/segments/seg_7c4e2a9b1d3f50618293a4b5/members?limit=50",
  headers=headers,
)
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET",
		"https://api.orbit.devotel.io/api/v1/contacts/segments/seg_7c4e2a9b1d3f50618293a4b5/members?limit=50",
		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/segments/seg_7c4e2a9b1d3f50618293a4b5/members?limit=50')
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/segments/seg_7c4e2a9b1d3f50618293a4b5/members?limit=50');
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);

Pagination metadata comes back under meta.pagination.cursor — pass that value as ?cursor= on the next request. Each member is the contact row as of the last materialisation.

{
  "data": [
    {
      "id": "cnt_1f3a9b2c4d5e60718293a4b5c6",
      "segment_added_at": "2026-08-20T09:14:00.000Z",
      "email": "jane@globex.com",
      "display_name": "Jane Doe"
    }
  ],
  "meta": {
    "request_id": "req_cdp_seg_members",
    "pagination": {
      "cursor": "eyJzYW47bGJpZDoxMTJ9",
      "has_more": true,
      "total": 314
    }
  }
}

3. Export a segment to CSV

GET /api/v1/contacts/segments/{id}/export.csv — streams the materialised membership as a CSV attachment; requires contacts:export.

For a one-shot CSV handoff (BI tooling, an agency export) read the member rows straight off the segment; for a recurring profile or membership export into a warehouse destination, use GET /api/v1/cdp/reverse-etl/profile-exports and GET /api/v1/cdp/reverse-etl/segment-exports to route it through a configured reverse-ETL destination instead. Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/contacts/segments/seg_7c4e2a9b1d3f50618293a4b5/export.csv" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

const res = await fetch(
  'https://api.orbit.devotel.io/api/v1/contacts/segments/seg_7c4e2a9b1d3f50618293a4b5/export.csv',
  {
    headers: { 'X-API-Key': process.env.ORBIT_API_KEY! },
  },
)
console.log(await res.text())

Python

import os, requests

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

package main

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

func main() {
	req, _ := http.NewRequest("GET",
		"https://api.orbit.devotel.io/api/v1/contacts/segments/seg_7c4e2a9b1d3f50618293a4b5/export.csv",
		nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	resp, _ := http.DefaultClient.Do(req)
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

Ruby

require 'net/http'

uri = URI('https://api.orbit.devotel.io/api/v1/contacts/segments/seg_7c4e2a9b1d3f50618293a4b5/export.csv')
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/segments/seg_7c4e2a9b1d3f50618293a4b5/export.csv');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
]);

echo curl_exec($ch);

contact_id,email,first_name,last_name,segment_added_at
cnt_1f3a9b2c4d5e60718293a4b5c6,jane@globex.com,Jane,Doe,2026-08-20T09:14:00.000Z
cnt_9b7c6d5e4f3a2b1c0d9e8f7a6,sam@globex.com,Sam,Ortiz,2026-08-19T17:02:12.000Z

4. Page through the raw event stream oldest-first

GET /api/v1/cdp/events/export?since=…&until=…&cursor=… — chronological bulk export; requires contacts:read.

This is the archive/re-hydration walk of cdp_events: oldest-first, filtered by any of since / until / type / contact_id / user_id / anonymous_id, with an opaque keyset cursor on each response. Keep the cursor and loop until has_more flips false. For GDPR Art. 20 portability pass the subject’s contact_id; for a warehouse re-sync volume pass nothing and let it walk the full window. Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/cdp/events/export?since=2026-08-01T00:00:00Z&limit=200" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

const res = await fetch(
  'https://api.orbit.devotel.io/api/v1/cdp/events/export?since=2026-08-01T00:00:00Z&limit=200',
  {
    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/cdp/events/export?since=2026-08-01T00:00:00Z&limit=200",
  headers=headers,
)
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET",
		"https://api.orbit.devotel.io/api/v1/cdp/events/export?since=2026-08-01T00:00:00Z&limit=200",
		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/cdp/events/export?since=2026-08-01T00:00:00Z&limit=200')
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/cdp/events/export?since=2026-08-01T00:00:00Z&limit=200');
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": {
    "data": [
      {
        "id": "evt_5713c2d9a8b4",
        "type": "track",
        "event_name": "Order Completed",
        "contact_id": "cnt_1f3a9b2c4d5e60718293a4b5c6",
        "received_at": "2026-08-18T09:03:12.118Z"
      }
    ],
    "pagination": {
      "cursor": "eyJzMW0=",
      "has_more": true
    }
  },
  "meta": {
    "request_id": "req_cdp_events_export",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

POST /api/v1/contacts/{id}/gdpr/erasure-request then POST /api/v1/cdp/erasure/{erasureId}/propagate — owners/admins file; propagation is a destructive compliance action, owner/admin only.

Filing the request starts the cancellable cooling-off window (per-tenant, 7 days by default) and returns the erasure_* id you keep for the rest of the flow. After the scheduler completes the soft-erasure cascade (see the erasure propagation guide for the cascade order), call the propagate endpoint on that id to fan the deletion out to every wired Nango destination (HubSpot, Salesforce, Braze, Iterable, and the like) — each destination’s outcome is audit-logged and returned inline. Request — step 1: file the request

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/contacts/cnt_1f3a9b2c4d5e60718293a4b5c6/gdpr/erasure-request" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" 

Node.js

const res = await fetch(
  'https://api.orbit.devotel.io/api/v1/contacts/cnt_1f3a9b2c4d5e60718293a4b5c6/gdpr/erasure-request',
  {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.ORBIT_API_KEY!,
      'Content-Type': 'application/json',
    },
  },
)
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/cnt_1f3a9b2c4d5e60718293a4b5c6/gdpr/erasure-request",
  headers=headers,
)
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST",
		"https://api.orbit.devotel.io/api/v1/contacts/cnt_1f3a9b2c4d5e60718293a4b5c6/gdpr/erasure-request",
		nil)
	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/cnt_1f3a9b2c4d5e60718293a4b5c6/gdpr/erasure-request')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/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/cnt_1f3a9b2c4d5e60718293a4b5c6/gdpr/erasure-request');
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',
]);

echo curl_exec($ch);

{
  "data": {
    "id": "erasure_8a2c4e6f1b3d5a7c",
    "contact_id": "cnt_1f3a9b2c4d5e60718293a4b5c6",
    "status": "pending",
    "requested_by": "user_981735",
    "requested_at": "2026-08-26T12:00:00.000Z",
    "cooling_off_ends_at": "2026-09-02T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_cdp_erasure_file",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

A 409 ERASURE_COOLING_OFF_ACTIVE means a request is already pending or executing for this contact — cancel it via POST /api/v1/contacts/{id}/gdpr/erasure-request/{requestId}/cancel before filing again. Request — step 2: propagate the completed erasure downstream Substitute the erasure_* id returned in step 1 once the cascade reports status: completed.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/cdp/erasure/erasure_8a2c4e6f1b3d5a7c/propagate" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" 

Node.js

const res = await fetch(
  'https://api.orbit.devotel.io/api/v1/cdp/erasure/erasure_8a2c4e6f1b3d5a7c/propagate',
  {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.ORBIT_API_KEY!,
      'Content-Type': 'application/json',
    },
  },
)
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/cdp/erasure/erasure_8a2c4e6f1b3d5a7c/propagate",
  headers=headers,
)
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST",
		"https://api.orbit.devotel.io/api/v1/cdp/erasure/erasure_8a2c4e6f1b3d5a7c/propagate",
		nil)
	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/cdp/erasure/erasure_8a2c4e6f1b3d5a7c/propagate')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/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/cdp/erasure/erasure_8a2c4e6f1b3d5a7c/propagate');
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',
]);

echo curl_exec($ch);

Each destination outcome is written to the tenant’s audit chain for Art. 17 proof; a skipped_no_connection row means the tenant hasn’t wired that destination. Propagate BEFORE the hard-delete cascade purges the contact row — after hard-delete the endpoint returns 409 ERASURE_CONTACT_NOT_FOUND, and identifiers can no longer be resolved for downstream destinations.

{
  "data": {
    "erasure_id": "erasure_8a2c4e6f1b3d5a7c",
    "contact_id": "cnt_1f3a9b2c4d5e60718293a4b5c6",
    "outcomes": [
      { "destination": "hubspot", "mode": "delete", "outcome": "dispatched" },
      { "destination": "braze", "mode": "suppress", "outcome": "dispatched" },
      { "destination": "salesforce", "mode": "delete", "outcome": "skipped_no_connection" }
    ]
  },
  "meta": {
    "request_id": "req_cdp_erasure_propagate",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Discover the predictive-model catalog

GET /api/v1/cdp/predictive-models

The server-owned catalog lists the four built-in models — churn_propensity, conversion_intent, lifetime_value, engagement_fatigue — with each model’s kind, output unit, algorithm, and the six first-party features it fits over. Call it first so the model path param on train/score/activate/drift always carries a valid key. Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/cdp/predictive-models" \
  -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/cdp/predictive-models', {
  method: 'GET',
  headers: { 'X-API-Key': process.env.ORBIT_API_KEY! },
})
const { data } = (await res.json()) as {
  data: {
    count: number
    models: Array<{
      model: 'churn_propensity' | 'conversion_intent' | 'lifetime_value' | 'engagement_fatigue'
      kind: 'classification' | 'regression'
      title: string
      description: string
      output_unit: 'probability' | 'cents'
      algorithm: string
      feature_names: string[]
    }>
  }
}
console.log(data.count, data.models.map((m) => m.model))

Response

{
  "data": {
    "count": 4,
    "models": [
      {
        "model": "churn_propensity",
        "kind": "classification",
        "title": "Churn propensity",
        "description": "Probability that an active contact will churn, learned from contacts whose lifecycle outcome is already resolved.",
        "output_unit": "probability",
        "algorithm": "logistic_regression_l2",
        "feature_names": [
          "tenure_days",
          "recency_days",
          "messages_sent",
          "messages_received",
          "events_30d",
          "distinct_events_30d"
        ]
      }
    ]
  },
  "meta": {
    "request_id": "req_cdp_model_catalog",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Worked chain: catalog → train → score

The typical integration first trains the model on the tenant’s resolved-outcome history, then scores the model’s activation population — so the catalog call above is followed by a train call; a successful train returns status: "trained" (200), while a thin resolved-outcome sample returns the same report with status: "insufficient_data" (HTTP 422 — wait for more labelled outcomes, then retry).

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/cdp/predictive-models/churn_propensity/train" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json"

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/cdp/predictive-models/churn_propensity/train',
  {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.ORBIT_API_KEY!,
      'Content-Type': 'application/json',
    },
  },
)
const report = (await res.json()) as {
  data:
    | {
        status: 'trained'
        model: string
        kind: 'classification' | 'regression'
        algorithm: string
        output_unit: string
        feature_names: string[]
        training: { sample_count: number; auc?: number; log_loss?: number; accuracy?: number }
        intercept: number
        coefficients: Array<{ feature: string; weight: number }>
      }
    | { status: 'insufficient_data'; model: string; kind: string; reason: string; sample_count: number }
}
if (report.data.status === 'insufficient_data') {
  console.log('Not enough labelled outcomes yet:', report.data.reason)
} else {
  console.log(`AUC ${report.data.training.auc} over ${report.data.training.sample_count} samples`)
}

For the full train → evaluate → score loop, CLV tiering, drift checks, and uplift persuadability, see the CDP predictive models guide.

Check a predictive model for input drift

GET /api/v1/cdp/predictive-models/{model}/drift

Compare the live scoring population’s feature + prediction distribution against the model’s training distribution. A PSI above your threshold (default 0.25) means the live distribution has shifted enough to question the ranking. Run drift before trusting a ranking from a fit you trained days ago. Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/cdp/predictive-models/engagement_fatigue/drift?window_days=30&bins=10&threshold=0.25" \
  -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/cdp/predictive-models/engagement_fatigue/drift?window_days=30&bins=10&threshold=0.25',
  {
    method: 'GET',
    headers: { 'X-API-Key': process.env.ORBIT_API_KEY! },
  },
)
const { data } = (await res.json()) as {
  data: {
    status: 'ok'
    model: string
    drift_detected: boolean
    drifted_features: string[]
    max_psi: number
    features: Array<{ feature: string; psi: number; status: 'stable' | 'moderate_shift' | 'significant_shift'; alert: boolean }>
    prediction: { psi: number; status: string; alert: boolean; output_unit: string }
    window_days: number
    training_sample_count: number
    window_sample_count: number
  }
}
if (data.drift_detected) {
  console.log('retrain:', data.drifted_features)
}

Response

{
  "data": {
    "status": "ok",
    "model": "engagement_fatigue",
    "kind": "classification",
    "window_days": 30,
    "bins": 10,
    "threshold": 0.25,
    "training_sample_count": 4802,
    "window_sample_count": 1187,
    "drift_detected": true,
    "drifted_features": ["recency_days"],
    "max_psi": 0.3104,
    "features": [
      { "feature": "recency_days", "psi": 0.3104, "status": "significant_shift", "alert": true },
      { "feature": "tenure_days", "psi": 0.091, "status": "stable", "alert": false },
      { "feature": "messages_sent", "psi": 0.114, "status": "stable", "alert": false },
      { "feature": "messages_received", "psi": 0.077, "status": "stable", "alert": false },
      { "feature": "events_30d", "psi": 0.133, "status": "moderate_shift", "alert": false },
      { "feature": "distinct_events_30d", "psi": 0.095, "status": "stable", "alert": false }
    ],
    "prediction": {
      "psi": 0.1872,
      "status": "moderate_shift",
      "alert": false,
      "output_unit": "probability"
    }
  },
  "meta": {
    "request_id": "req_cdp_model_drift",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Materialise a predictive-model segment

POST /api/v1/cdp/predictive-models/{model}/activate

Turns the ranked top-N score list into a first-class static segment — the same one-click activation the dashboard’s Audience → Predictive models page performs. Returns 201 with the created segment and its member count, and 422 with the fit report when the model is not fitted yet. Request

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/cdp/predictive-models/churn_propensity/activate" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Churn risk — winback", "limit": 50 }'

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/cdp/predictive-models/churn_propensity/activate',
  {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.ORBIT_API_KEY!,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ name: 'Churn risk — winback', limit: 50 }),
  },
)
const { data } = (await res.json()) as {
  data: {
    materialized: boolean
    model: string
    segment?: { id: string; name: string; description?: string }
    member_count?: number
    population_scored?: number
    activation_ready?: boolean
  }
}
console.log(`${data.member_count} profiles in segment ${data.segment?.id}`)

Response

{
  "data": {
    "materialized": true,
    "model": "churn_propensity",
    "segment": {
      "id": "segment_01HZR29VA1T4KXQ9DNGN0ZQ3F6",
      "name": "Churn risk — winback",
      "description": "Predictive activation list from the \"Churn propensity\" model — top 50 of 1,284 scored profiles by probability. Static snapshot; ready for audience activation.",
      "auto_refresh": false
    },
    "member_count": 50,
    "population_scored": 1284,
    "activation_ready": true
  },
  "meta": {
    "request_id": "req_cdp_model_activate",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Because activation WRITES a segment, this endpoint requires the contacts:write scope (catalog/train/score/drift only need contacts:read).

API Reference

All Endpoints

Worked request and response samples