Embedded Web SDK API

The endpoints that the @devotel-orbit/web browser SDK calls at runtime. Mounted at /sdk/* (no /api/v1 prefix) so client-side embeds don’t have to think about API versions. Base path: https://api.orbit.devotel.io/sdk Authentication: Tenant public key (dv_live_pk_*) sent in the X-API-Key header. CORS is open — these endpoints are designed to be called directly from your website’s JavaScript. Why a separate base path: server-to-server keys (dv_live_sk_* in the Authorization header) are secret. Browser-embedded public keys (dv_live_pk_* in X-API-Key) are safe to ship in client-side code. The split base prevents accidentally exposing a server key in a browser bundle. Response envelope: every endpoint returns the platform envelope — data plus a meta block with request_id and timestamp. Each endpoint below pairs the raw cURL with the equivalent @devotel-orbit/web TypeScript client — one endpoint, one SDK method, same envelope. The sample pairs follow the SDK sample coverage policy.

Identify

Resolve an anonymous browser visitor to a known contact (by email or phone). Events captured before the visitor identifies attach to the right contact once the server backfills. The response returns the resolved contact_id:

curl -X POST 'https://api.orbit.devotel.io/sdk/identify' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: dv_live_pk_your_key' \
  -d '{
    "anonymous_id": "anon_8f3c2b1d",
    "email": "jane@example.com",
    "display_name": "Jane Doe"
  }'

import { OrbitPersonalization } from '@devotel-orbit/web';

const orbit = new OrbitPersonalization({
  apiUrl: 'https://api.orbit.devotel.io',
  publicKey: 'dv_live_pk_your_key',
});

await orbit.identify({
  email: 'jane@example.com',
  display_name: 'Jane Doe',
});
// orbit.anonymousId is the browser-sticky id the SDK sends for you.

{
  "data": {
    "contact_id": "contact_7d21f0a9b8c4e5f2",
    "anonymous_id": "anon_8f3c2b1d"
  },
  "meta": {
    "request_id": "req_9c04b1e8a2",
    "timestamp": "2026-08-27T12:04:31.512Z"
  }
}

anonymous_id is required (it ties the call back to the browser session); the SDK sends its browser-sticky id for you. Include at least one of email or phone — omitting both returns a 400/422 validation error. display_name and traits are optional. Identifying is idempotent: repeat calls with the same email or phone update the same contact_id.

Method	Path	Purpose
`POST`	`/sdk/identify`	Resolve / merge anonymous → known contact

Track

Capture one or more custom events (page view, button click, video watched, item added to cart). Events flow into the same store that powers segmentation, scoring, and contact timelines. A batch returns the count of accepted events:

curl -X POST 'https://api.orbit.devotel.io/sdk/track' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: dv_live_pk_your_key' \
  -d '{
    "anonymous_id": "anon_8f3c2b1d",
    "events": [
      { "name": "page_viewed", "properties": { "url": "https://example.com/pricing" } },
      { "name": "item_added_to_cart", "properties": { "sku": "shoe-42", "value": 89.99 } }
    ]
  }'

import { OrbitPersonalization } from '@devotel-orbit/web';

const orbit = new OrbitPersonalization({
  apiUrl: 'https://api.orbit.devotel.io',
  publicKey: 'dv_live_pk_your_key',
});

orbit.track({
  name: 'item_added_to_cart',
  properties: { sku: 'shoe-42', value: 89.99 },
});

{
  "data": {
    "accepted": 2
  },
  "meta": {
    "request_id": "req_3f81d2c7e4",
    "timestamp": "2026-08-27T12:04:33.104Z"
  }
}

Send up to 50 events per call. Each event needs a name; properties and an ISO-8601 timestamp are optional (properties are capped at 8 KiB per event — split or trim larger payloads). The required anonymous_id identifies the browser session, so events captured before a visitor identifies still attach to the right contact. You can also pass identity ({ "email": ... } or { "phone": ... }) to attribute the batch to an existing contact without an identify call. In the SDK, track() batches events client-side and attaches the sticky anonymous id automatically.

Method	Path	Purpose
`POST`	`/sdk/track`	Capture one or more custom events

Personalize

Resolve the right personalization slot variant for the current visitor at runtime. The response carries the slot’s content, CTA, matched variant, and the segment that matched (or null when the slot default applied):

curl 'https://api.orbit.devotel.io/sdk/personalize?slot=hero_banner&anonymous_id=anon_8f3c2b1d' \
  -H 'X-API-Key: dv_live_pk_your_key'

import { OrbitPersonalization } from '@devotel-orbit/web';

const orbit = new OrbitPersonalization({
  apiUrl: 'https://api.orbit.devotel.io',
  publicKey: 'dv_live_pk_your_key',
});

const { content, cta_url, cta_text } =
  await orbit.getPersonalization('hero_banner');

{
  "data": {
    "slot": "hero_banner",
    "segment": "high_intent",
    "content": "<h2>Welcome back — your cart is waiting</h2>",
    "cta_url": "/cart",
    "cta_text": "Resume checkout",
    "variant": "hero-banner-high-intent"
  },
  "meta": {
    "request_id": "req_e7a92c1bf1",
    "timestamp": "2026-08-27T12:04:35.276Z"
  }
}

Pass phone or email alongside anonymous_id to resolve the visitor’s segment. With no matching variant, content is empty and variant is null — render your site’s own default. Responses carry a Cache-Control: private, max-age=60 header, so repeat pulls from the same browser hit the local cache.

Method	Path	Purpose
`GET`	`/sdk/personalize`	Resolve a personalization slot for the calling visitor

In-app feed

Pull the visitor’s eligible content cards and in-app messages — the feed the OrbitInApp renderer polls. Authoring lives under Messages → In-app (PUT /api/v1/messages/in-app); this endpoint is the owned-channel delivery leg. No carrier is involved — delivery is this pull from your own site or app:

curl 'https://api.orbit.devotel.io/sdk/in-app/feed?anonymous_id=anon_8f3c2b1d' \
  -H 'X-API-Key: dv_live_pk_your_key'

import { OrbitInApp } from '@devotel-orbit/web';

const inApp = new OrbitInApp({
  apiUrl: 'https://api.orbit.devotel.io',
  publicKey: 'dv_live_pk_your_key',
});

// Already assembled: expired + dismissed surfaces dropped, pinned cards
// first, messages priority-sorted.
const { cards, messages } = await inApp.fetchFeed();

{
  "data": {
    "enabled": true,
    "cards": [
      {
        "id": "card_quikrewards",
        "cardType": "captioned_image",
        "title": "Quik Rewards",
        "imageUrl": "https://cdn.example.com/quikrewards.webp",
        "linkUrl": "https://example.com/rewards",
        "pinned": true
      }
    ],
    "messages": [
      {
        "id": "msg_backinstock",
        "messageType": "modal",
        "body": "Back in stock — the shoes you viewed",
        "priority": 90,
        "buttons": [
          { "id": "buy", "text": "Shop now", "url": "/p/shoe-42" }
        ]
      }
    ]
  },
  "meta": {
    "request_id": "req_4a1c8f2d9b",
    "timestamp": "2026-08-27T12:05:12.004Z"
  }
}

Pass anonymous_id on the query so segment-targeted surfaces resolve: a surface authored with segmentLabels is delivered only when that visitor’s resolved segment matches. When the channel is disabled or nothing is authored, the feed is { "enabled": false, "cards": [], "messages": [] } — never an error. Responses carry Cache-Control: private, max-age=30, stale-while-revalidate=60, because per-visitor targeting must not leak into shared caches. fetchFeed() returns the feed already assembled — expired and locally-dismissed surfaces dropped, pinned cards first, messages priority-sorted — an empty feed on any transport error.

Method	Path	Purpose
`GET`	`/sdk/in-app/feed`	Pull the eligible content cards + in-app messages for a visitor

In-app events

Report engagement with a content card or in-app message — an impression, click, or dismissal. button_id identifies which CTA a click hit, and user_id carries your host app’s end-user id when one is known:

curl -X POST 'https://api.orbit.devotel.io/sdk/in-app/events' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: dv_live_pk_your_key' \
  -d '{
    "type": "click",
    "surface_id": "msg_backinstock",
    "anonymous_id": "anon_8f3c2b1d",
    "button_id": "buy",
    "occurred_at": "2026-08-27T12:05:44.110Z"
  }'

import { OrbitInApp } from '@devotel-orbit/web';

const inApp = new OrbitInApp({
  apiUrl: 'https://api.orbit.devotel.io',
  publicKey: 'dv_live_pk_your_key',
});

await inApp.reportEvent('click', 'msg_backinstock', 'buy');
// Shortcut for the dismiss flow: persists locally, then reports.
await inApp.dismiss('msg_backinstock');

{
  "data": { "accepted": 1 },
  "meta": {
    "request_id": "req_7c2e9a1f45",
    "timestamp": "2026-08-27T12:05:44.301Z"
  }
}

The event lands in the same event store as /sdk/track, so in-app engagement shows on the contact timeline and in analytics alongside on-site behaviour. The row is recorded under anonymous_id alone; a later /sdk/identify backfills it onto the contact, exactly like pre-identify tracked events. The SDK surfaces (OrbitInApp in the web SDK, OrbitInAppClient in the React Native SDK) report these events for you — call this endpoint directly only when you render the feed with your own components.

Method	Path	Purpose
`POST`	`/sdk/in-app/events`	Report an in-app impression / click / dismissal

Anonymous unload track

Send the pending event batch on page unload without embedding a key. Modern browsers flush on unload with fetch({ keepalive: true }) — the key stays on the X-API-Key header and this endpoint is never touched. A small tail of older browsers lacks keepalive, so the SDK falls back to navigator.sendBeacon against this key-free path:

curl -X POST 'https://api.orbit.devotel.io/sdk/track/anonymous' \
  -H 'Content-Type: application/json' \
  -d '{
    "anonymous_id": "anon_8f3c2b1d",
    "events": [
      { "name": "page_hidden", "timestamp": "2026-08-27T12:06:01.512Z" }
    ]
  }'

const payload = JSON.stringify({
  anonymous_id: 'anon_8f3c2b1d',
  events: [{ name: 'page_hidden', timestamp: new Date().toISOString() }],
});
navigator.sendBeacon(
  'https://api.orbit.devotel.io/sdk/track/anonymous',
  new Blob([payload], { type: 'application/json' }),
);

{
  "data": { "accepted": 1 },
  "meta": {
    "request_id": "req_1b7d3e8f02",
    "timestamp": "2026-08-27T12:06:01.744Z"
  }
}

Always 202, with no authentication — a page unloading cannot act on an error, so every outcome is accepted. Events land in a tenant-unattributed staging area keyed only by the anonymous_id, and the next /sdk/identify call reconciles them into the resolving tenant. Until reconciliation the rows carry no tenant attribution, so a keyless caller cannot steer events into another tenant. Note the asymmetry: staging accepts the same event body as /sdk/track, but unlike /sdk/track no identity block can resolve it early — only a later identify attaches it.

Method	Path	Purpose
`POST`	`/sdk/track/anonymous`	Key-free unload-flush fallback event intake

Server-to-server calls

The /sdk/identify and /sdk/track endpoints also accept calls from your backend — a CRM sync, an order pipeline, a nightly export job — not just from the browser. Same envelope and body shape, sent with the tenant public key (dv_live_pk_) in the X-API-Key header. The endpoints accept both transports, but use the right key class: server-to-server pipelines send the public key, never a secret key (dv_live_sk_). Browsers remain the preferred integration for behavioural events — the @devotel-orbit/web package batches them safely, handles CORS, and manages anonymous ids automatically. Only use the server-side path when the events genuinely originate in your backend. A Node.js server-side push (a CRM-side event push, plain fetch idiom — the typed helpers on the Node.js SDK page wrap the same endpoints when you want them):

curl -X POST 'https://api.orbit.devotel.io/sdk/identify' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: dv_live_pk_your_key' \
  -d '{ "anonymous_id": "crm_sync_8f3c2b1d", "email": "jane@example.com" }'

curl -X POST 'https://api.orbit.devotel.io/sdk/track' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: dv_live_pk_your_key' \
  -d '{
    "anonymous_id": "crm_sync_8f3c2b1d",
    "identity": { "email": "jane@example.com" },
    "events": [
      { "name": "crm_trial_started", "properties": { "plan": "pro" } }
    ]
  }'

const ORBIT_API = 'https://api.orbit.devotel.io';
const PUBLIC_KEY = process.env.ORBIT_PUBLIC_KEY; // dv_live_pk_...

async function sdkPost(path: string, payload: unknown): Promise<unknown> {
  const res = await fetch(`${ORBIT_API}/sdk/${path}`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': PUBLIC_KEY,
    },
    body: JSON.stringify(payload),
  });
  if (!res.ok) throw new Error(`/sdk/${path} failed: ${res.status}`);
  return (await res.json()).data;
}

await sdkPost('identify', {
  anonymous_id: 'crm_sync_8f3c2b1d',
  email: 'jane@example.com',
  display_name: 'Jane Doe',
});

await sdkPost('track', {
  anonymous_id: 'crm_sync_8f3c2b1d',
  identity: { email: 'jane@example.com' },
  events: [
    { name: 'crm_trial_started', properties: { plan: 'pro' } },
    { name: 'crm_invoice_paid', properties: { amount: 120.0 } },
  ],
});

import os, requests

headers = {
    "Content-Type": "application/json",
    "X-API-Key": os.environ["ORBIT_PUBLIC_KEY"],  # dv_live_pk_...
}
base = "https://api.orbit.devotel.io/sdk/"

requests.post(
    base + "identify",
    headers=headers,
    json={
        "anonymous_id": "crm_sync_8f3c2b1d",
        "email": "jane@example.com",
        "display_name": "Jane Doe",
    },
)

requests.post(
    base + "track",
    headers=headers,
    json={
        "anonymous_id": "crm_sync_8f3c2b1d",
        "identity": {"email": "jane@example.com"},
        "events": [
            {"name": "crm_trial_started", "properties": {"plan": "pro"}},
            {"name": "crm_invoice_paid", "properties": {"amount": 120.0}},
        ],
    },
)

base := "https://api.orbit.devotel.io/sdk/"
headers := map[string]string{
  "Content-Type": "application/json",
  "X-API-Key":    os.Getenv("ORBIT_PUBLIC_KEY"), // dv_live_pk_...
}

identify := map[string]any{
  "anonymous_id": "crm_sync_8f3c2b1d",
  "email":        "jane@example.com",
  "display_name": "Jane Doe",
}
// POST identify JSON to base+"identify" with headers

track := map[string]any{
  "anonymous_id": "crm_sync_8f3c2b1d",
  "identity":     map[string]string{"email": "jane@example.com"},
  "events": []map[string]any{
    {"name": "crm_trial_started", "properties": map[string]any{"plan": "pro"}},
    {"name": "crm_invoice_paid", "properties": map[string]any{"amount": 120.0}},
  },
}
// POST track JSON to base+"track" with headers

headers = {
  "Content-Type" => "application/json",
  "X-API-Key" => ENV.fetch("ORBIT_PUBLIC_KEY"), # dv_live_pk_...
}

def sdk_post(path, payload, headers)
  http = Net::HTTP.new("api.orbit.devotel.io", 443)
  http.use_ssl = true
  request = Net::HTTP::Post.new("/sdk/#{path}")
  headers.each { |k, v| request[k] = v }
  request.body = payload.to_json
  http.request(request)
end

sdk_post("identify", {
  anonymous_id: "crm_sync_8f3c2b1d",
  email: "jane@example.com",
  display_name: "Jane Doe"
}, headers)

sdk_post("track", {
  anonymous_id: "crm_sync_8f3c2b1d",
  identity: { email: "jane@example.com" },
  events: [
    { name: "crm_trial_started", properties: { plan: "pro" } },
    { name: "crm_invoice_paid", properties: { amount: 120.0 } },
  ]
}, headers)

$headers = [
  "Content-Type: application/json",
  "X-API-Key: " . getenv("ORBIT_PUBLIC_KEY"), // dv_live_pk_...
];

function sdkPost(string $path, array $payload, array $headers): void {
  $ch = curl_init("https://api.orbit.devotel.io/sdk/" . $path);
  curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => json_encode($payload),
  ]);
  curl_exec($ch);
}

sdkPost("identify", [
  "anonymous_id" => "crm_sync_8f3c2b1d",
  "email" => "jane@example.com",
  "display_name" => "Jane Doe",
], $headers);

sdkPost("track", [
  "anonymous_id" => "crm_sync_8f3c2b1d",
  "identity" => ["email" => "jane@example.com"],
  "events" => [
    ["name" => "crm_trial_started", "properties" => ["plan" => "pro"]],
    ["name" => "crm_invoice_paid", "properties" => ["amount" => 120.0]],
  ],
], $headers);

Batching discipline is yours on the server. The browser SDK transparently batches up to 25 events every 2 seconds and flushes on page exit; a raw server-side caller must decide this trade-off explicitly. Group events into a single /sdk/track batch (up to 50 per call) instead of firing one HTTP request per event — both to stay under the per-key pacing and to keep CORS/browser semantics out of the loop. Grouping by callers like a CRM import also lets you pass a single shared identity in one batch call rather than one call per contact.

Use the SDK instead of raw fetch

For browser integrations, use the @devotel-orbit/web package — it handles the anonymous id for you (a stable id persisted in the visitor’s browser), batches events into groups of up to 25 every 2 seconds, and flushes on page exit. The raw-fetch flow above becomes:

npm install @devotel-orbit/web

import { OrbitPersonalization } from '@devotel-orbit/web';

const orbit = new OrbitPersonalization({
  apiUrl: 'https://api.orbit.devotel.io',
  publicKey: 'dv_live_pk_your_key',
});

await orbit.identify({
  email: 'jane@example.com',
  display_name: 'Jane Doe',
});

orbit.track({
  name: 'item_added_to_cart',
  properties: { sku: 'shoe-42', value: 89.99 },
});

const { content, cta_url, cta_text } =
  await orbit.getPersonalization('hero_banner');

Every page has a stable orbit.anonymousId you can reference in server-side flows; orbit.reset() clears a remembered identity for explicit logouts.

API Reference

All Endpoints

Embedded Web SDK API: identify visitors and track events

Embedded Web SDK API

Identify

Track

Personalize

In-app feed

In-app events

Anonymous unload track

Server-to-server calls

Use the SDK instead of raw fetch

See also

​Embedded Web SDK API

​Identify

​Track

​Personalize

​In-app feed

​In-app events

​Anonymous unload track

​Server-to-server calls

​Use the SDK instead of raw fetch

​See also

Embedded Web SDK API

Identify

Track

Personalize

In-app feed

In-app events

Anonymous unload track

Server-to-server calls

Use the SDK instead of raw fetch

See also