REST API recipes

This is the cookbook the SDK index points at: since no SDK is published to a package registry yet, every recipe here is REST-first with the Node SDK (source-only, unpublished) as the second snippet. Ten tasks cover the integrations most teams build first — loyalty, OAuth integrations, and internal team chat round out the messaging, verification, contacts, and risk loops below. Each one is self-contained — pick the task you need, run it against the sandbox with a dv_test_sk_… key, then swap in your live key. Authenticate every request with X-API-Key. Base URL is https://api.orbit.devotel.io/api/v1 — sandbox is the same URL with a test key, not a separate host. Full primer: API integration.

Task index

#	Task	Endpoints used
1	Send a message, poll status, receive the webhook	`POST /messages/sms`, `GET /messages/:id`, webhook
2	Handle a 429 with `retry_after`	`POST /messages/sms` (429 path)
3	Verify an OTP, end to end	`POST /verify/send`, `POST /verify/check`
4	List and cursor-paginate	`GET /messages`
5	Batch-import contacts, poll the import job	`POST /contacts/imports`, `GET /contacts/imports/:id`
6	Score a destination before you send	`POST /risk/score`
7	Run a loyalty earn → preview → redeem round trip	`POST /loyalty/preview`, `GET /loyalty/members/:contactId`, `POST /loyalty/members/:contactId/redeem`
8	Open an OAuth connection and pull synced records	`POST /integrations/connect`, `GET /integrations/:id/status`, `GET /integrations/:id/data`
9	Coordinate the team in a team-chat channel	`GET /team-chat/channels`, `POST /team-chat/channels/:id/messages`
10	Errors as recipes	decision table

1. Send a message, poll status, receive the webhook

Send one SMS, learn its id, then track delivery two ways: a direct status poll and a delivery webhook. Webhooks are the production answer — poll once to confirm the send works, then move to events. Send:

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-conf-98421" \
  -d '{
    "from": "+16572262362",
    "to": "+14155552671",
    "body": "Your order 98421 shipped."
  }'

Node SDK

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

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

const message = await orbit.messages.send({
  channel: 'sms',
  to: '+14155552671',
  body: 'Your order 98421 shipped.',
});
// message.id — keep it for the status poll below.

A 202 Accepted returns the persisted send in the standard envelope. data.id (msg_…) is your handle; data.status starts as sent (or test_sent in sandbox) and moves as the carrier reports. Poll status once:

cURL

curl https://api.orbit.devotel.io/api/v1/messages/msg_01HXYZ \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

Node SDK

const status = await orbit.messages.get('msg_01HXYZ');
// status.status: sent | delivered | failed | queued | test_sent

Receive the webhook instead. Register one endpoint in Settings → Webhooks subscribed to message.delivered and message.failed (or * for everything). Orbit POSTs each status change to you; verify the X-Orbit-Signature header before trusting the body — verification is one function call per API integration → Webhooks. Polling is for the first integration smoke test; production consumers subscribe. Canonical pages: Messaging API, Webhook events.

2. Handle a 429 with `retry_after`

When your send rate passes the per-key limit, the API answers 429 with a body that names the wait inside the envelope (error.retry_after) and again as a Retry-After header. Read whichever your HTTP client exposes; honor it before any fallback backoff — doubling on your own can retry inside the window and re-429.

cURL

# The 429 body is self-describing; extract retry_after with jq.
RESP=$(curl -s -X POST https://api.orbit.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from": "+16572262362", "to": "+14155552671", "body": "hi"}')

echo "$RESP" | jq -r '.error.retry_after // 0'  # seconds to wait

Node SDK

import { OrbitRateLimitError } from '@devotel-orbit/node';

try {
  await orbit.messages.send({ channel: 'sms', to, body });
} catch (e) {
  if (e instanceof OrbitRateLimitError) {
    // 429 — the server-provided wait is in `details`.
    const waitSeconds = Number(e.details?.retry_after ?? 5);
    await new Promise(r => setTimeout(r, waitSeconds * 1000));
    // retry here — same idempotency key if you set one, so a retry can't double-send
  } else {
    throw e;
  }
}

The full retry-wrapper pattern (capped exponential fallback when the server didn’t name a wait) lives in API error handling by example; per-channel rates are in API integration → Rate limits.

3. Verify an OTP, end to end

Two requests: send the code, then check what the user typed. The platform generates, delivers, and expires the code; your backend never stores or compares it. Send — capture data.verification_id from the response:

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/verify/send \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "channel": "sms",
    "code_length": 6
  }'

Node SDK

const verification = await orbit.verify.send({
  to: '+14155552671',
  channel: 'sms',
  codeLength: 6,
});
// verification.verification_id — pass to check with the user's code.

Check — the user’s answer plus the id from send:

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/verify/check \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verification_id": "vrf_9f2a1c…",
    "code": "483920"
  }'

Node SDK

const result = await orbit.verify.check({
  verificationId: 'vrf_9f2a1c…',
  code: '483920',
});
// result.status: approved | failed | expired

status: "approved" is the only pass. failed means the code didn’t match; re-check with the same verification_id until attempts_remaining hits 0, then send a fresh one. expired means the send’s TTL lapsed — send again. In sandbox, a test key simulates delivery; find the expected code in the verification’s dashboard row. Canonical page: Verify API. A longer REST-only walkthrough (the same two calls plus webhook fallback): Verify integration without our SDK.

4. List and cursor-paginate

List endpoints return stable cursors — no offsets, so concurrent inserts can’t shift your page. Request the first page without a cursor, then pass meta.pagination.cursor until meta.pagination.has_more is false.

cURL

# page 1
curl "https://api.orbit.devotel.io/api/v1/messages?limit=100" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

# page N — substitute the cursor from the previous response
curl "https://api.orbit.devotel.io/api/v1/messages?limit=100&cursor=eyJpZCI6Im1zZ18wMUhYWVovLi4uIn0=" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

Node SDK

let cursor: string | undefined;
do {
  const page = await orbit.messages.list({ limit: 100, cursor });
  for (const message of page.data) {
    // consume one message per iteration
  }
  cursor = page.meta.pagination.has_more
    ? page.meta.pagination.cursor
    : undefined;
} while (cursor);

A wrong or expired cursor is a 422 INVALID_CURSOR — restart the iteration without a cursor; never reuse cursors across requests changed in filters or across retries older than the same-minute window. Full table of cursor-vs-offset endpoints: Pagination.

5. Batch-import contacts, poll the import job

For anything past a few hundred rows, skip per-row POST /contacts calls and enqueue one async import. The endpoint accepts the parsed CSV as a rows array, returns 202 with a job_id, and runs the insert in the background. Poll the job id for progress.

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/contacts/imports \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "launch-list.csv",
    "merge_strategy": "skip",
    "rows": [
      { "phone": "+14155552671", "first_name": "Ada", "source": "launch_list" },
      { "phone": "+442071234567", "first_name": "Grace", "source": "launch_list" }
    ]
  }'

Node SDK

const enqueued = await orbit.contacts.imports.create({
  fileName: 'launch-list.csv',
  mergeStrategy: 'skip', // 'merge' updates existing rows instead
  rows: [
    { phone: '+14155552671', first_name: 'Ada', source: 'launch_list' },
    { phone: '+442071234567', first_name: 'Grace', source: 'launch_list' },
  ],
});
// enqueued.job_id — poll it below.

Poll the job until status is no longer pending/running:

cURL

curl https://api.orbit.devotel.io/api/v1/contacts/imports/imp_01HZYK \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

Node SDK

const job = await orbit.contacts.imports.get('imp_01HZYK');
// job.status: pending | running | completed | failed | cancelled

merge_strategy: "skip" (the default) leaves existing contacts untouched on duplicate keys; "merge" updates them with your new values. A completed row besides the failed ones reports per-row outcomes; rows that failed validation are listed as skipped, not imported as empty records. A 503 IMPORT_QUEUE_UNAVAILABLE means the background queue is briefly down — retry after a few seconds; don’t fall back to hundreds of single creates under load. Canonical pages: Contacts API, Import contacts guide.

6. Score a destination before you send

POST /risk/score fuses the platform’s fraud detectors into one 0–100 verdict you can query before committing an SMS send or verify. It’s read-only and advisory — it never dispatches, so it’s safe to burn before every high-cost send.

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/risk/score \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "+14155552671",
    "channel": "sms",
    "message_body": "Your order shipped — track it at https://acme.example/t/98421"
  }'

Node SDK

const score = await orbit.request('POST', '/api/v1/risk/score', {
  destination: '+14155552671',
  channel: 'sms',
  messageBody: 'Your order shipped — track it at https://acme.example/t/98421',
});
// score.score (0–100), score.band (low|elevated|high|critical),
// score.recommendation (allow|review|block)

Branch on recommendation: allow — proceed to the send; review — queue for a human only if the send is high-value; block — suppress the send and log the decision. band is the same verdict bucketed; score (0–100) is the worst-signal composite — the per-channel breakdown names which detector fired. This is a gate on your send decision, not a platform block: enforcement stays in your code, and outbound SMS still exits only through the platform. Canonical page: Risk API. The pumping-attack context this protects against: SMS pumping protection.

7. Run a loyalty earn → preview → redeem round trip

Points come from events you already send to the CDP — loyalty computes a member’s balance from your event history when you check it, so there is no separate loyalty ledger to sync. The round trip: dry-run the program with preview, read a member’s balance, then burn points. Preview — evaluate your active program (or an override in the request body) against sample events. Nothing writes to the database, so burn this freely while you tune earn rules:

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/loyalty/preview \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "event_name": "account.created" },
      { "event_name": "order-completed", "properties": { "total": 189.95 } }
    ]
  }'

Node SDK

const preview = await orbit.request('POST', '/api/v1/loyalty/preview', {
  events: [
    { event_name: 'account.created' },
    { event_name: 'order-completed', properties: { total: 189.95 } },
  ],
});
// preview.program_source: default | custom
// preview.state — per-event attribution, earned, lifetime, tier

Read a member’s balance — points accrue from CDP events your app already emits (track on the CDP API); the read endpoint projects those events into the member’s standing on demand. Two compensation events join order-completed and loyalty.points_redeemed in the ledger: loyalty.points_adjusted (an operator’s manual credit or debit) and loyalty.program_configured (a revision under a config sentinel contact that members never write):

cURL

curl https://api.orbit.devotel.io/api/v1/loyalty/members/cnt_9f8a7b6c \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

Node SDK

const member = await orbit.request(
  'GET',
  '/api/v1/loyalty/members/cnt_9f8a7b6c',
);
// member.contact_id, member.balance, member.tier, member.traits

balance is the spendable remainder; use GET /loyalty/members (paginated) to list every member or a specific id for one. The traits block also exposes loyalty_points_balance, loyalty_tier, and friends exactly as segments and journeys see them. Redeem — burn points atomically. Concurrent redemptions against the same contact serialize, so a double-click can’t overspend:

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/loyalty/members/cnt_9f8a7b6c/redeem \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "points": 500, "reward": "10% off next order", "reference": "ord_9182" }'

Node SDK

const redemption = await orbit.request(
  'POST',
  '/api/v1/loyalty/members/cnt_9f8a7b6c/redeem',
  { points: 500, reward: '10% off next order', reference: 'ord_9182' },
); // 201 Created
// redemption.redemption_event_id — your handle; debited; new balance

Success is 201 Created with the redemption event id and the post-burn balance. An overspend returns 409 INSUFFICIENT_POINTS with the available remainder — burden the retry on a smaller amount or abort. Manual operator adjustments (POST /loyalty/members/:contactId/adjust) share the same overspend-safe path. Canonical page: Loyalty API. The program-design walkthrough this loop plugs into: Loyalty program setup.

8. Open an OAuth connection and pull synced records

The integrations loop is connect → status → data: start the OAuth flow, confirm the connection formed, then read the synced records. Connect and sync trigger are owner/admin-gated; status and data are reads any scoped key can run. Start the connect flow — get the auth_url you redirect the operator to:

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/integrations/connect \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "integration_id": "hubspot" }'

Node SDK

const connection = await orbit.request('POST', '/api/v1/integrations/connect', {
  integrationId: 'hubspot',
});
// connection.auth_url — redirect the operator here; the provider's
// consent screen completes the handshake.

A provider with no OAuth credentials registered fails 404; an integration server misconfigured answers 503. Either is terminal — fix in Settings → Integrations, not in your retry loop. Confirm status — the OAuth popup closing is not proof the connection formed; ask before you read data:

cURL

curl https://api.orbit.devotel.io/api/v1/integrations/hubspot/status \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

Node SDK

const status = await orbit.request('GET', '/api/v1/integrations/hubspot/status');
// status.connected — false means the popup closed without consent,
// the provider rejected, or credentials never formed.

connected: false resolves cleanly (with an empty sync list) rather than an error, so branch on it without a try/catch. Once connected, the same payload carries the connection’s metadata and per-sync status. Pull synced records — name the model (contacts, deals, …) in the query:

cURL

curl "https://api.orbit.devotel.io/api/v1/integrations/hubspot/data?model=contacts" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

Node SDK

const records = await orbit.request(
  'GET',
  '/api/v1/integrations/hubspot/data?model=contacts',
);
// records — the synced rows for that model

An empty array is a valid answer — it means the connection is live but the first sync hasn’t landed records for that model yet. An owner/admin kicks an immediate run with POST /integrations/:id/sync { "sync_name": "contacts" } instead of waiting for the scheduled cadence; a 502 on data reads means the upstream fetch failed, retry after a beat. Canonical page: Integrations API. The full CRM loop (webhooks, writeback, debugging): Connect HubSpot & Salesforce end to end.

9. Coordinate the team in a team-chat channel

Team chat is the internal surface — channels, DMs, and huddles for the operators running your workspace, membership-gated so nothing ever reaches a customer. Useful when a back-office bot or dashboard posts handoff notes: list your channels, post to one, read it back. List your channels — every read is membership-scoped, so you see only channels your API key’s principal belongs to:

cURL

curl https://api.orbit.devotel.io/api/v1/team-chat/channels \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

Node SDK

const channels = await orbit.request('GET', '/api/v1/team-chat/channels');
// channels[] — ids you can post into; a non-member gets 403.

Post to a channel:

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/team-chat/channels/tch_abc123/messages \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Handoff complete — incident inc_123 resolved." }'

Node SDK

const posted = await orbit.request(
  'POST',
  `/api/v1/team-chat/channels/${channelId}/messages`,
  { body: 'Handoff complete — incident inc_123 resolved.' },
);
// posted.id — handle for threads, edits, reactions below.

A 403 here is a membership gate, not a key problem — the same principal must be on the channel from the same identity; have the owner add you with POST /team-chat/channels/:id/members. Reactions, threads, DMs, and huddles follow the same shape off the message id. Canonical page: TeamChat API. The operator workflows behind it: Team Chat guide.

10. Errors as recipes

Errors are recipes too — the failure classes in API error handling by example map one-to-one onto the tasks above. Branch on error.code, never on message text.

Failure	`error.code`	HTTP	This cookbook’s response
Non-E.164 `to` on send	`INVALID_PHONE_NUMBER`	422	Normalize the destination, resend — same body, same 422 if you don’t.
Send over key limit	`RATE_LIMITED`	429	Task 2: read `retry_after`, wait, retry.
Over-cap recipient	`FREQUENCY_CAP_EXCEEDED`	429	Defer that recipient by `details.retry_after_seconds`; continue the batch.
Key issue	`INVALID_API_KEY`	401	Check the key’s prefix (`dv_test_sk_` vs `dv_live_sk_`) and revocation state in Settings → API Keys.
Wallet below channel minimum	`INSUFFICIENT_BALANCE`	402	Top up; do not retry the same send.
Reused idempotency key	`IDEMPOTENCY_KEY_REUSED`	409	Key + different body — generate a fresh key per logical send.
Bad cursor on a list	`INVALID_CURSOR`	422	Task 4: restart iteration without a cursor.
Import queue down	`IMPORT_QUEUE_UNAVAILABLE`	503	Task 5: retry after a few seconds.
Wrong/expired OTP code	(status `failed` / `expired` on `/verify/check`, not a thrown error)	200	Task 3: retry the same `verification_id` until attempts run out, then resend.
Loyalty overspend	`INSUFFICIENT_POINTS`	409	Task 7: read the available remainder and retry smaller, or abort — never re-send the same points.
Integration not connected	(body `connected: false` on `GET /integrations/:id/status`, not a thrown error)	200	Task 8: the OAuth popup closed without consent — re-open the connect flow, don’t loop on data.
Provider OAuth credentials not registered	`404` from `/integrations/connect`	404	Task 8: register the provider’s OAuth credentials in Settings → Integrations; terminal, not retryable.
Team-chat principal not on channel	`NOT_A_MEMBER`	403	Task 9: have a channel owner add the principal (`POST /team-chat/channels/:id/members`); retrying never helps.

Anything not in this table: read meta.docs_url in the error envelope — it links to the code’s remedy in the Error Code Reference. Branch on the retriable-vs-terminal table in API error handling by example.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

REST API recipes: task-by-task curl and Node cookbook

REST API recipes

Task index

1. Send a message, poll status, receive the webhook

2. Handle a 429 with `retry_after`

3. Verify an OTP, end to end

4. List and cursor-paginate

5. Batch-import contacts, poll the import job

6. Score a destination before you send

7. Run a loyalty earn → preview → redeem round trip

8. Open an OAuth connection and pull synced records

9. Coordinate the team in a team-chat channel

10. Errors as recipes

See also

​REST API recipes

​Task index

​1. Send a message, poll status, receive the webhook

​2. Handle a 429 with retry_after

​3. Verify an OTP, end to end

​4. List and cursor-paginate

​5. Batch-import contacts, poll the import job

​6. Score a destination before you send

​7. Run a loyalty earn → preview → redeem round trip

​8. Open an OAuth connection and pull synced records

​9. Coordinate the team in a team-chat channel

​10. Errors as recipes

​See also

REST API recipes

Task index

1. Send a message, poll status, receive the webhook

2. Handle a 429 with `retry_after`

3. Verify an OTP, end to end

4. List and cursor-paginate

5. Batch-import contacts, poll the import job

6. Score a destination before you send

7. Run a loyalty earn → preview → redeem round trip

8. Open an OAuth connection and pull synced records

9. Coordinate the team in a team-chat channel

10. Errors as recipes

See also