API recipes: operations endpoints

The operations endpoints cookbook: six operational surfaces endpoint-guides cover conceptually but only sample once. Each recipe below is a runnable loop — read, write, decide — over the exact endpoints the linked page documents. Base URL is https://api.orbit.devotel.io/api/v1 throughout; authenticate with X-API-Key and a test key (dv_test_sk_…) for the sandbox.

1. Verify approvals: run the second-officer round trip

The four-eyes gate on Verify approvals has a full queue lifecycle — policy, queue, decision — and a client needs all three calls to drive it. Read the current policy to predict whether your next change will queue (any authenticated member can read it):

cURL

curl https://api.orbit.devotel.io/api/v1/verify/approvals/settings \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

Turn the gate on (owner/admin only — the requester’s own key is usually not this):

cURL

curl -X PUT https://api.orbit.devotel.io/api/v1/verify/approvals/settings \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "require_approval_default": true,
    "resend_burst_threshold": 25,
    "resend_burst_window_seconds": 300
  }'

From the next request onward, an OTP template edit or an over-threshold resend burst returns gated: true and queues instead of applying. Read the queue the approver’s key sees:

cURL

curl https://api.orbit.devotel.io/api/v1/verify/approvals/pending \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

Decide one item — approve, or reject with a reason the requester reads back. The approver must differ from the requester: a self-approve fails 409 FOUR_EYES_VIOLATION before anything moves.

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/verify/approvals/vap_9f2a1c/approve \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

cURL — reject instead

curl -X POST https://api.orbit.devotel.io/api/v1/verify/approvals/vap_9f2a1c/reject \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Tighten the wording and re-submit." }'

An approved item executes in its own plane — a template body applies to its verification profile; a resend burst re-enters the normal dispatch path. Expected results are 200 with data.settings on reads, 200 with the decided item on approve/reject, and 403 on any of the three writes from a non-owner/admin key. Every decision lands in the audit log as verify.approval.approved / verify.approval.rejected. Canonical pages: Verify approvals: set up the second-officer gate, OTP approvals reference.

2. Fallback chains: preview the resolved cascade, then let smart-send arm it

A per-message cascade_policy resolves an ordered fallback set without sending when you run it through POST /messages/route-preview. Preview before you arm — the Fallback chains guide’s step 7 names both preview endpoints; this is the API loop it refers to. Preview the router’s primary plus the cascade — same body shape as smart-send, read-only:

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/messages/route-preview \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "body": "Your order 98421 shipped.",
    "message_type": "transactional",
    "urgency": "medium",
    "country": "US",
    "cascade_policy": {
      "fallback_channels": ["sms"],
      "auto_fallback": true
    }
  }'

The reply carries the recommendation block the smart route preview guide documents, plus a resolved cascade block when cascade_policy was in the request: the fallback channel list, the ordering (static / adaptive / off), and a cost estimate. A 200 with data.cascade.ordering: "off" means the policy suppressed the arm — the send below would ride the primary channel with no fallback stamped. Arm it with the real send — the same cascade_policy on POST /messages/smart-send stamps the resolved chain onto the message’s metadata as fallback_channels, so a terminal DLR on the primary escalates to the next entry:

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/messages/smart-send \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "body": "Your order 98421 shipped.",
    "message_type": "transactional",
    "urgency": "medium",
    "cascade_policy": {
      "fallback_channels": ["sms"],
      "auto_fallback": true
    }
  }'

202 Accepted returns the persisted send with data.channel naming the router’s primary pick and the fallback set stamped on its metadata. voice and fax are filtered out of cascade_policy.fallback_channels — the per-message cascade is messaging-only; OTP step-up chains that admit voice belong on a Verify profile, per the chain-type table in Fallback chains. Canonical pages: Smart-send fallback chains, Smart route preview.

3. Message history: run the `q=` search DSL over the API

The search message history guide documents the fielded DSL; the API loop adds the list endpoint, URL-encoding rules, and cursor pagination. Encode the expression — spaces to %20, : to %3A, > to %3E — and it rides GET /messages alongside the pagination params:

cURL

curl "https://api.orbit.devotel.io/api/v1/messages?q=channel%3Asms%20status%3Afailed%20created%3E2026-08-20&limit=25" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

Page the matches with the same cursor contract as any list — meta.pagination.cursor while has_more is true:

cURL

curl "https://api.orbit.devotel.io/api/v1/messages?q=channel%3Asms%20status%3Afailed%20created%3E2026-08-20&limit=25&cursor=eyJpZCI6InJtc2dfMDFIWFYvLi4uIn0=" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

A malformed expression returns 422 INVALID_QUERY naming the rejected field, operator, or clause (INVALID_QUERY_FIELD on an unknown field, INVALID_QUERY_SYNTAX on an unterminated quote) — fix the named clause; never retry the same string. Each matching row carries both the provider-side identifier (external_id) and the canonical Orbit id (id, msg_…), so a look-up can deep-link into the message detail page. Canonical pages: Search message history, Pagination.

4. SMPP: set the no-delivery receipt window on a termination rule

The SMPP receipt timeout window guide sets receipt_timeout_seconds on a termination rule’s deliver hop (10–120 s, platform default 30). This loop hashes the exact API body the guided contract ships and where it goes. Write the rule — absorb submit_sm traffic onto WhatsApp with a 45-second UNDELIV window:

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/messaging/termination/rules \
  -H "X-API-Key: dv_live_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OTP via WhatsApp — 45s fallback window",
    "priority": 10,
    "enabled": true,
    "mode": "enforce",
    "direction": "mt_absorb",
    "ingress_kind": "smpp_submit",
    "match": {
      "all": [
        { "field": "dest_addr", "op": "prefix", "value": "+91" }
      ]
    },
    "actions": [
      {
        "kind": "deliver",
        "channel": "whatsapp",
        "template_name": "verify_user",
        "template_language": "en",
        "on_failure": "next",
        "receipt_timeout_seconds": 45
      },
      { "kind": "absorb" }
    ]
  }'

201 Created returns the rule. Out-of-range or non-integer windows (25.5, 0, 121) answer 422 at rule-write time, and a rule in shadow mode evaluates without moving traffic until you flip it to enforce. The deadline only arms for submissions whose registered_delivery requested a receipt: a bind that never requests receipts gets none from the timeout either. Canonical pages: SMPP receipt timeout window, Send-side DLR model.

5. Brand identity: read the trust posture

The Brand Identity API rolls six registration flows — 10DLC, toll-free, WhatsApp Business, RCS, branded calling, and per-number regulatory KYC — into one trust score plus a prioritized action list. One read tells you how verified the brand is everywhere; the operator loop reads the summary, then works the nextActions queue top-down. Read the posture:

cURL

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

No typed SDK helper wraps this endpoint yet — Node uses the generic request() escape hatch, Python uses client.request (paths relative to /api/v1 there):

Node.js

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

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

const { data: status } = await orbit.request(
  'GET',
  '/api/v1/brand-identity/status',
);
// status.summary.trustScore — 0-100; status.nextActions — urgent first

Python

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

status = client.request("GET", "/brand-identity/status")
print(status["data"]["summary"]["trustScore"])  # 0-100

Read the envelope top to bottom. data.summary.trustScore is verified / applicable rounded to an integer 0–100, with overallState naming the rollup (verified / action_required / …). Each entry in data.channels[] reports one of five states — not_started, in_progress, verified, action_required, unavailable — plus a manageHref into the dashboard screen that fixes it. data.nextActions[] is already sorted urgent before todo, so walk it in order; it is the same list the dashboard brand-trust widget renders. Handle the degraded 200. A per-channel source that cannot be reached never fails the response — it returns 200 with that channel at state: "unavailable" and drops the channel out of scoring. Watch summary.applicable: when it falls (six channels to five in the reference page’s example), trustScore recomputed against the channels that did answer, so an outage never drags the score down. If every source read fails, applicable is 0 and overallState is unavailable with trustScore: 0 — distinguish “nothing verified yet” from “everything unreachable” by reading applicable, never the score. Retry on unavailable with ordinary backoff; the state is transient and self-clears. Expected results are 200 with data.summary on a healthy read and 401 / 403 on a missing or under-scoped key. Any authenticated role can read it. Canonical pages: Brand Identity API, Brand identity & trust score concept.

6. Risk score: pre-send guard loop

The Risk API fuses SMS-pumping risk, URL reputation, and your own Verify Fraud Guard / Voice Biometrics scores into one composite verdict. The main cookbook’s #6 score a destination runs the full call; this loop is the smallest useful version — destination plus channel — and the send gate you wire the recommendation into. The endpoint is read-only and advisory: it sends nothing and enforces nothing, so the allow/hold/drop decision is yours. Score the destination:

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

Read the band, not just the number. Score bands decode as 0–24 low, 25–49 elevated, 50–79 high, 80–100 critical, and data.recommendation maps them to an action: critical → block, high → review, elevated | low → allow. The per-channel data.channels[] array names the detector that drove the verdict, so a block is never a black box. Passing message_body adds the outbound link-reputation scan; pass-through verify_signal / voice_biometrics_signal scores fold your own detectors into the same number. Wire the recommendation into a send gate:

Node.js

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

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

async function scoreBeforeSend(destination: string, body: string) {
  const { data: verdict } = await orbit.request(
    'POST',
    '/api/v1/risk/score',
    {
      body: { destination, channel: 'sms', message_body: body },
    },
  );

  switch (verdict.recommendation) {
    case 'allow':
      return orbit.messages.send({ channel: 'sms', to: destination, body });
    case 'review':
      // hold for an operator — send only after the queue decides
      return queueForReview(destination, body, verdict);
    case 'block':
      return null; // drop the send; verdict.channels[] names the driver
  }
}

Expected results are 200 with data.score / data.band / data.recommendation on every well-formed ask, and 422 naming the bad field on a malformed destination or channel. An empty ask — no pass-through signals, no message_body — returns a clean score: 0 / band: "low" rather than an error. How you act on review is tenant policy: hold-and-send or drop is your gate to build; the API only advises. Canonical pages: Risk API, Risk verdict model.

WhatsApp

Developer console

Contact center

Guides

Messaging Controls

Audience & Support Tools

API recipes: operations endpoints

API recipes: operations endpoints

1. Verify approvals: run the second-officer round trip

2. Fallback chains: preview the resolved cascade, then let smart-send arm it

3. Message history: run the `q=` search DSL over the API

4. SMPP: set the no-delivery receipt window on a termination rule

5. Brand identity: read the trust posture

6. Risk score: pre-send guard loop

See also

​API recipes: operations endpoints

​1. Verify approvals: run the second-officer round trip

​2. Fallback chains: preview the resolved cascade, then let smart-send arm it

​3. Message history: run the q= search DSL over the API

​4. SMPP: set the no-delivery receipt window on a termination rule

​5. Brand identity: read the trust posture

​6. Risk score: pre-send guard loop

​See also

API recipes: operations endpoints

1. Verify approvals: run the second-officer round trip

2. Fallback chains: preview the resolved cascade, then let smart-send arm it

3. Message history: run the `q=` search DSL over the API

4. SMPP: set the no-delivery receipt window on a termination rule

5. Brand identity: read the trust posture

6. Risk score: pre-send guard loop

See also