API recipes: operations endpoints

Four 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.

WhatsApp

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

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

​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

See also