Worked samples

Worked request and response samples

Copy a request body as written, substitute your own number, and compare the response envelope. Every sample pairs a plain E.164 number — Devotel Orbit forwards it as the CAMARA subject — against a dv_test_sk_* sandbox key, so no operator is contacted, no credits are deducted, and the response carries meta.test_mode: true. X-Test-Mode: true behaves the same way on a dashboard-session-authenticated call; a live key (dv_live_sk_*) always reaches the operator.

Authentication, per-service subscription, and the response envelope

Two things gate every call on this page. First, your Orbit API key in the X-API-Key header: dv_live_sk_* for live traffic, dv_test_sk_* for the zero-charge sandbox. Second, a per-CAMARA-service subscription with the operator behind your deployment — Number Verification, SIM Swap, Device Location, Quality-on-Demand, Carrier Billing, KYC Match, and Connectivity Insights are each enabled per deployment as the operator contract covers them. Read that enrollment back before you gate live traffic: GET /api/v1/numbers/network-apis/status answers { "data": { "enabled": true } } when a CAMARA operator is configured, and any signal dip on an unenrolled deployment fails closed with a 503 instead of a fabricated result (catalogued below). Every 2xx response arrives in the same { data, meta } envelope. data carries the operator’s answer with CAMARA field names preserved; meta carries request_id, timestamp, and test_mode. Errors invert the envelope: error.code, error.status, error.message, plus error.details when a field-level or upstream cause is available.

The 38 operations in five families

Silent identity proof — number-verification:verify (possession), sim-swap:check + sim-swap:retrieve-date + sim-swap/subscriptions (recency + continuous monitoring), device-swap:check (handset change), device-roaming-status:retrieve + device-roaming-status/subscriptions (visited country), device-status:reachability, device-location:verify, number-recycling:check (tenure), scam-signal:assess (active-call / forwarding / swap dip), kyc-match:match (operator KYC), age-verification:verify (age gate), carrier-billing:charge (direct carrier billing).
Unified risk fusion — risk:score returns the weighted 0–100 composite with reason codes; identity:gate returns the same composite as an allow | review | deny decision plus review_or_block for a funnel.
Quality-on-Demand — create/read/extend/delete qod-sessions for an on-demand QoS data bearer.
Network slices + connectivity — book/read/delete network-slices reservations; check or subscribe to connectivity-insights:check-network-quality congestion verdicts.
Bring-your-own-prefix routing — internet-access/announcements (announce / list / withdraw), route-holds:assess (is a failover switch safe now), and failover-events (the audit feed).

The numbered sections below work one representative operation from each family end to end; every remaining operation on the page follows the same request shape (E.164 subject + optional window/limit params) and the same { data, meta } envelope.

E.164 or hashed subject — exactly one. Every operation that takes a subscriber subject accepts "phoneNumber" in E.164, or its SHA-256 equivalent "hashedPhoneNumber" — never both in one body. Send the plain E.164 form; Orbit forwards it to the operator as the CAMARA subject and masks it in every error detail. Devotel Orbit itself only ever speaks JSON toward the operator — an XML body shape appears only on operators that still run a legacy XML HLR endpoint, and even then it is the operator-facing contract, never yours.

1. Number Verification (Silent Auth)

POST /api/v1/numbers/network-apis/number-verification:verify

Pass "phoneNumber" (E.164) or its SHA-256 equivalent "hashedPhoneNumber" — exactly one. Add accessToken when your device already completed the three-legged operator flow; without it the call still runs, but server-context possession is only as strong as the operator deployment allows.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/number-verification:verify" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+14155552671"
}'

Node.js

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/numbers/network-apis/number-verification:verify",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_TEST_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ phoneNumber: "+14155552671" }),
  },
);
console.log(await res.json());

Node.js (SDK request escape hatch)

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

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });
const data = await orbit.request(
  "POST",
  "/api/v1/numbers/network-apis/number-verification:verify",
  { phoneNumber: "+14155552671" },
);
console.log(data);

{
  "data": {
    "devicePhoneNumberVerified": true
  },
  "meta": {
    "request_id": "req_network_nva_s1",
    "timestamp": "2026-09-09T12:00:00.000Z",
    "test_mode": true
  }
}

devicePhoneNumberVerified: false means not confirmed — treat it as no assertion, never as proof of absence.

2. SIM Swap check

POST /api/v1/numbers/network-apis/sim-swap:check

maxAge is the look-back in hours (1..2400, default 240). A swapped: true inside the window is a strong account-takeover signal — step up before you accept the session.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/sim-swap:check" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+14155552671",
  "maxAge": 240
}'

Node.js

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/numbers/network-apis/sim-swap:check",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_TEST_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ phoneNumber: "+14155552671", maxAge: 240 }),
  },
);
console.log(await res.json());

{
  "data": {
    "swapped": false
  },
  "meta": {
    "request_id": "req_network_ssc_s2",
    "timestamp": "2026-09-09T12:00:01.000Z",
    "test_mode": true
  }
}

For the precise timestamp when you want the raw fact instead of a boolean, POST /sim-swap:retrieve-date returns the operator’s last SIM-change time under the same envelope. For continuous monitoring, POST /sim-swap/subscriptions enrolls the number and the operator POSTs a CloudEvent to your notificationUrl the moment a swap occurs — see section 7 for that round trip.

2b. SIM Swap subscription — create + the webhook it triggers

POST /api/v1/numbers/network-apis/sim-swap/subscriptions

Create returns the operator-issued subscription id, status, and expiry (the live handler confirms with a 201 — accept any 2xx). notificationUrl must be HTTPS; notificationAuthToken is sent to your sink as a bearer token on every delivery so you can authenticate the operator’s call.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/sim-swap/subscriptions" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+14155552671",
  "notificationUrl": "https://your-app.example.com/webhooks/camara",
  "notificationAuthToken": "replace-with-a-long-random-bearer"
}'

Node.js

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/numbers/network-apis/sim-swap/subscriptions",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_TEST_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      phoneNumber: "+14155552671",
      notificationUrl: "https://your-app.example.com/webhooks/camara",
      notificationAuthToken: "replace-with-a-long-random-bearer",
    }),
  },
);
console.log(await res.json());

{
  "data": {
    "id": "sub_1b3d5f7a9c2e4g6h8i0j",
    "status": "ACTIVE",
    "startsAt": "2026-09-09T12:00:08.000Z",
    "expiresAt": "2026-09-16T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_network_sub_s9b",
    "timestamp": "2026-09-09T12:00:08.000Z",
    "test_mode": true
  }
}

The webhook it triggers. The moment the SIM behind the watched number is swapped, the operator POSTs a CloudEvent to your notificationUrl. Your endpoint receives this exact envelope — switch on type and read the subject from data.subscriptionDetail.device.phoneNumber:

Webhook (POST to your notificationUrl)

{
  "id": "evt_01HZQX9K3N5WQ8R2M4V7D6A1BC",
  "source": "https://operator.example.com/sim-swap-subscriptions/v0",
  "type": "org.camaraproject.sim-swap-subscriptions.v0.swapped",
  "specversion": "1.0",
  "datacontenttype": "application/json",
  "time": "2026-09-09T14:22:31.000Z",
  "data": {
    "subscriptionId": "sub_1b3d5f7a9c2e4g6h8i0j",
    "subscriptionDetail": {
      "device": { "phoneNumber": "+14155552671" }
    }
  }
}

Receiver patterns for this and every other Orbit webhook family (signature checks, retry windows, ack discipline) are in the webhook payload cookbook.

3. Device Location verification

POST /api/v1/numbers/network-apis/device-location:verify

Send a circle — centre (latitude, longitude) and radius in metres (2,000..200,000) — and the operator answers whether the device is inside it without revealing where it actually is. verificationResult is TRUE, FALSE, PARTIAL (coverage overlap, not a clean hit), or UNKNOWN (no fix inside maxAge seconds, 60..3600).

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/device-location:verify" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+14155552671",
  "latitude": 37.7749,
  "longitude": -122.4194,
  "radius": 5000,
  "maxAge": 300
}'

Node.js

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/numbers/network-apis/device-location:verify",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_TEST_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      phoneNumber: "+14155552671",
      latitude: 37.7749,
      longitude: -122.4194,
      radius: 5000,
      maxAge: 300,
    }),
  },
);
console.log(await res.json());

{
  "data": {
    "verificationResult": "TRUE"
  },
  "meta": {
    "request_id": "req_network_dlv_s3",
    "timestamp": "2026-09-09T12:00:02.000Z",
    "test_mode": true
  }
}

When the operator’s fix overlaps your circle but does not sit cleanly inside it, the answer is PARTIAL with the estimated matchRate — the verification-area read you treat as “probable, step up” rather than a clean pass:

200 (PARTIAL)

{
  "data": {
    "verificationResult": "PARTIAL",
    "matchRate": 68
  },
  "meta": {
    "request_id": "req_network_dlv_s3p",
    "timestamp": "2026-09-09T12:00:02.500Z",
    "test_mode": true
  }
}

4. Device reachability + roaming status

POST /api/v1/numbers/network-apis/device-status:reachability

The operator’s network-asserted reachability (CONNECTED_DATA, CONNECTED_SMS, or NOT_CONNECTED) for a device, without contacting it. A NOT_CONNECTED read is a corroborating fraud signal; CONNECTED_SMS tells you SMS delivery alone is still possible.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/device-status:reachability" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+14155552671"
}'

Node.js

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/numbers/network-apis/device-status:reachability",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_TEST_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ phoneNumber: "+14155552671" }),
  },
);
console.log(await res.json());

{
  "data": {
    "reachabilityStatus": "CONNECTED_SMS"
  },
  "meta": {
    "request_id": "req_network_dsr_s4",
    "timestamp": "2026-09-09T12:00:03.000Z",
    "test_mode": true
  }
}

The same call against a device the network cannot see at all answers NOT_CONNECTED — nothing is dispatched to the handset; the verdict comes straight from the operator’s registration state:

200 (NOT_CONNECTED)

{
  "data": {
    "reachabilityStatus": "NOT_CONNECTED"
  },
  "meta": {
    "request_id": "req_network_dsr_s4n",
    "timestamp": "2026-09-09T12:00:03.500Z",
    "test_mode": true
  }
}

POST /api/v1/numbers/network-apis/device-roaming-status:retrieve

For the roaming variant, the same body shape applies — { phoneNumber } in, one verdict out:

{
  "data": {
    "roaming": true,
    "countryCode": "44",
    "countryName": "United Kingdom"
  },
  "meta": {
    "request_id": "req_network_rss_s5",
    "timestamp": "2026-09-09T12:00:04.000Z",
    "test_mode": true
  }
}

5. Unified Identity Risk score

POST /api/v1/numbers/network-apis/risk:score

Fuse every operator-asserted CAMARA signal (SIM swap, device status, device location, number verification, operator-asserted call forwarding, number recycling) with caller-held signals (roaming, reputationRiskLevel, callForwardingUnconditional) into ONE weighted 0–100 composite. Each live signal is fetched fail-soft — an unavailable operator is reported under signals_unavailable and contributes nothing, never a fabricated mid-score.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/risk:score" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+14155552671",
  "simSwapMaxAge": 240,
  "roaming": false,
  "context": { "event": "checkout", "amount_eur": 120 }
}'

Node.js

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/numbers/network-apis/risk:score",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_TEST_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      phoneNumber: "+14155552671",
      simSwapMaxAge: 240,
      roaming: false,
      context: { event: "checkout", amount_eur: 120 },
    }),
  },
);
console.log(await res.json());

{
  "data": {
    "decision": "allow",
    "risk_score": 12,
    "risk_level": "low",
    "reasons": [],
    "signals_evaluated": ["numberVerified", "simSwapped", "deviceReachability", "roaming"],
    "signals_unavailable": ["deviceLocationVerified"],
    "context": { "event": "checkout", "amount_eur": 120 }
  },
  "meta": {
    "request_id": "req_network_rsk_s6",
    "timestamp": "2026-09-09T12:00:05.000Z",
    "test_mode": true
  }
}

identity:gate is the funnel variant of the same scoring: same inputs (plus portedRecently and a claimed geofence), same composite, but the envelope is shaped for a gate — { decision, review_or_block, risk_score, risk_level, reasons } — so a live funnel can branch without re-interpreting the numeric score.

6. Scam Signal assessment

POST /api/v1/numbers/network-apis/scam-signal:assess

One real-time dip for the anti-APP-fraud gap the per-signal APIs leave: is the subscriber plausibly being socially-engineered on a live call right now? Returns the three anonymised operator signals (active call, call forwarding, recent SIM swap), a coarse risk_level, and a scam_signal_detected boolean. No call content is accessed; the consuming app still makes the final allow/review/block decision.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/scam-signal:assess" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+14155552671"
}'

Node.js

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/numbers/network-apis/scam-signal:assess",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_TEST_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ phoneNumber: "+14155552671" }),
  },
);
console.log(await res.json());

{
  "data": {
    "scam_signal_detected": false,
    "risk_level": "low",
    "signals": {
      "active_call": false,
      "call_forwarding": false,
      "sim_swap": false
    }
  },
  "meta": {
    "request_id": "req_network_scs_s7",
    "timestamp": "2026-09-09T12:00:06.000Z",
    "test_mode": true
  }
}

When the live-call indicators align — the subscriber is on a call while unconditional call forwarding and a very recent SIM change are also asserted — the verdict escalates. The three flags stay anonymised booleans: you never learn who the call is with or what the forwarding destination is.

200 (escalated)

{
  "data": {
    "scam_signal_detected": true,
    "risk_level": "high",
    "signals": {
      "active_call": true,
      "call_forwarding": true,
      "sim_swap": true
    }
  },
  "meta": {
    "request_id": "req_network_scs_s7h",
    "timestamp": "2026-09-09T12:00:06.500Z",
    "test_mode": true
  }
}

7. Quality-on-Demand session

POST /api/v1/numbers/network-apis/qod-sessions

Create an on-demand QoS bearer for a device: name the device (phone Number or IPv4), the applicationServer (IPv4), a qosProfile the operator offers, and duration in seconds (60..86400). Returns the operator-issued sessionId, qosStatus (REQUESTED → AVAILABLE / UNAVAILABLE), and expiry. GET reads a session’s current status, POST .../extend adds seconds, DELETE releases it early.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/qod-sessions" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "device": { "phoneNumber": "+14155552671" },
  "applicationServer": { "ipv4Address": "192.0.2.10" },
  "qosProfile": "QOS_L",
  "duration": 3600
}'

Node.js

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/numbers/network-apis/qod-sessions",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_TEST_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      device: { phoneNumber: "+14155552671" },
      applicationServer: { ipv4Address: "192.0.2.10" },
      qosProfile: "QOS_L",
      duration: 3600,
    }),
  },
);
console.log(await res.json());

{
  "data": {
    "sessionId": "sess_6f8a0c2d4e",
    "qosStatus": "REQUESTED",
    "expiresAt": "2026-09-09T13:00:00.000Z"
  },
  "meta": {
    "request_id": "req_network_qod_s8",
    "timestamp": "2026-09-09T12:00:07.000Z",
    "test_mode": true
  }
}

The live create handler confirms the booking with a 201 — accept any 2xx as success. Extend + delete round trip. POST .../extend takes requestedAdditionalDuration in seconds and answers 200 with the widened record; DELETE answers 204 with an empty body.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/qod-sessions/sess_6f8a0c2d4e/extend" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "requestedAdditionalDuration": 3600 }'

curl -X DELETE "https://api.orbit.devotel.io/api/v1/numbers/network-apis/qod-sessions/sess_6f8a0c2d4e" \
  -H "X-API-Key: dv_test_sk_your_key_here"

Node.js

const extended = await fetch(
  "https://api.orbit.devotel.io/api/v1/numbers/network-apis/qod-sessions/sess_6f8a0c2d4e/extend",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_TEST_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ requestedAdditionalDuration: 3600 }),
  },
);
console.log(await extended.json());

await fetch(
  "https://api.orbit.devotel.io/api/v1/numbers/network-apis/qod-sessions/sess_6f8a0c2d4e",
  { method: "DELETE", headers: { "X-API-Key": process.env.ORBIT_TEST_API_KEY! } },
);

{
  "data": {
    "sessionId": "sess_6f8a0c2d4e",
    "qosStatus": "AVAILABLE",
    "expiresAt": "2026-09-09T14:00:07.000Z",
    "duration": 7200
  },
  "meta": {
    "request_id": "req_network_qod_s28",
    "timestamp": "2026-09-09T12:00:28.000Z",
    "test_mode": true
  }
}

A DELETE returns 204 No Content with no body — treat the 2xx status alone as confirmation the session is gone; GET on the id afterward answers 404.

8. Continuous monitoring — subscription round trip

POST /api/v1/numbers/network-apis/sim-swap/subscriptions

Continuous monitoring is the real-time alternative to polling: create a subscription, and the operator POSTs a CloudEvent to your HTTPS notificationUrl the moment the watched number’s signal changes (roaming-on / roaming-off, a swap event, a congestion transition, a slice state change). The same pattern applies to device-roaming-status/subscriptions and connectivity-insights/subscriptions — create reads, read state, then DELETE to stop.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/sim-swap/subscriptions" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+14155552671",
  "notificationUrl": "https://your-app.example.com/webhooks/camara",
  "notificationAuthToken": "replace-with-a-long-random-bearer"
}'

Node.js

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/numbers/network-apis/sim-swap/subscriptions",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_TEST_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      phoneNumber: "+14155552671",
      notificationUrl: "https://your-app.example.com/webhooks/camara",
      notificationAuthToken: "replace-with-a-long-random-bearer",
    }),
  },
);
console.log(await res.json());

{
  "data": {
    "subscriptionId": "sub_1b3d5f7a9c2e4g6h8i0j",
    "status": "ACTIVE",
    "expiresAt": "2026-09-16T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_network_sub_s9",
    "timestamp": "2026-09-09T12:00:08.000Z",
    "test_mode": true
  }
}

The issued sub_1b3d5f7a9c2e4g6h8i0j is the same id GET /sim-swap/subscriptions/{subscriptionId} reads back in the subscription-state reads below — create and read are one flow: create, handle the CloudEvent (or poll), then DELETE the same id to stop.

Remaining envelopes by family

The eight walkthrough sections above cover ten of the thirty-two create/read/update operations this page lists; the page renders thirty-eight endpoints in total — those thirty-two plus six teardown calls, which answer 204 with no body and are documented in the closing teardown subsection so the page’s worked sequencing stays in family order. The remaining operations follow the same envelope conventions — a { data, meta } wrapper, operator fields carried verbatim under data, and the sandbox flag in meta.test_mode when a test-prefixed key is used. Each envelope below sits under the METHOD /path callout of the exact operation it documents, so the generated page splices it into that operation’s response slot; copy any pair straight into a pre-send risk check or a number-intelligence read without a trip to the sandbox.

Operator status — is a live operator configured?

GET /api/v1/numbers/network-apis/status

The dashboard’s live identity-verification tools gate on this flag. It reports a boolean only; integration secrets are never exposed.

{
  "data": {
    "enabled": true
  },
  "meta": {
    "request_id": "req_network_sts_s9",
    "timestamp": "2026-09-09T12:00:09.000Z"
  }
}

Availability read. When an operator is enrolled, the same call also names the services your deployment can exercise, so a client can gate each flow before spending a request on it:

200 (operator enrolled)

{
  "data": {
    "enabled": true,
    "services": [
      "number-verification",
      "sim-swap",
      "device-roaming-status",
      "device-location",
      "quality-on-demand",
      "connectivity-insights"
    ]
  },
  "meta": {
    "request_id": "req_network_sts_s9b",
    "timestamp": "2026-09-09T12:00:10.000Z"
  }
}

An unenrolled deployment answers { "data": { "enabled": false } } — the same shape as section 503’s fail-closed gate.

Bring-your-own-prefix routing — announcements and failover

POST /api/v1/numbers/network-apis/internet-access/announcements

Announcing a prefix carries your fenced proof of ownership and owning ASN; the operator acknowledges with the enrolled state. The same { prefix, asn, proofOfOwnershipToken } body also drives the withdraw call (DELETE on the same path) — documented in the teardown subsection below.

{
  "data": {
    "prefix": "192.0.2.0/24",
    "asn": 65552,
    "state": "ACTIVE"
  },
  "meta": {
    "request_id": "req_network_byo_s10",
    "timestamp": "2026-09-09T12:00:10.000Z",
    "test_mode": true
  }
}

GET /api/v1/numbers/network-apis/internet-access/announcements

The list read splits by address family. family echoes the optional ipv4 | ipv6 filter, or both when unfiltered.

{
  "data": {
    "ipv4": [{ "prefix": "192.0.2.0/24", "asn": 65552 }],
    "ipv6": [{ "prefix": "2001:db8::/32", "asn": 65552 }],
    "family": "both"
  },
  "meta": {
    "request_id": "req_network_byo_s11",
    "timestamp": "2026-09-09T12:00:11.000Z",
    "test_mode": true
  }
}

POST /api/v1/numbers/network-apis/internet-access/failover-events

The failover audit feed: who announced or withdrew which prefix, with a paging cursor in next when more rows exist. Both filters are optional: prefix restricts the feed to one announced CIDR, limit (1..500) caps the most-recent-first page.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/internet-access/failover-events?prefix=192.0.2.0%2F24&limit=50" \
  -H "X-API-Key: dv_test_sk_your_key_here"

Node.js

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/numbers/network-apis/internet-access/failover-events?prefix=192.0.2.0%2F24&limit=50",
  {
    method: "POST",
    headers: { "X-API-Key": process.env.ORBIT_TEST_API_KEY! },
  },
);
console.log(await res.json());

{
  "data": {
    "events": [
      {
        "type": "announcement",
        "prefix": "192.0.2.0/24",
        "asn": 65552,
        "at": "2026-09-08T09:11:00.000Z"
      }
    ],
    "next": null
  },
  "meta": {
    "request_id": "req_network_byo_s12",
    "timestamp": "2026-09-09T12:00:12.000Z",
    "test_mode": true
  }
}

POST /api/v1/numbers/network-apis/internet-access/route-holds:assess

Pre-flight a failover switch. Only an explicit all-pass over the ACTIVE hold set resolves switch_safe: true; a pending or missing hold read resolves unsafe. parent_prefix_hint carries the operator’s covering-route hint when it offers one; active_holds counts the holds evaluated.

{
  "data": {
    "switch_safe": true,
    "parent_prefix_hint": "192.0.0.0/8",
    "active_holds": 2
  },
  "meta": {
    "request_id": "req_network_byo_s13",
    "timestamp": "2026-09-09T12:00:13.000Z",
    "test_mode": true
  }
}

Carrier billing, age verification, and device swap — request + response pairs

The remaining pair-of-hands operations the walkthroughs skip, shown end to end with the exact body you send and the envelope you get back.

Carrier Billing charge

POST /api/v1/numbers/network-apis/carrier-billing:charge

Body: amount in major currency units (2 decimal places max), currency (ISO 4217), a 1..140-char description, plus optional merchantReference (echoed to the operator as referenceCode) and idempotencyKey so a retry can never double-bill. The route rejects any amount above the per-deployment cap before the call reaches the operator, and the live handler answers 201 with the operator’s payment record. The wallet-spend failure you can hit is a 402 INSUFFICIENT_BALANCE — the same balance gate the INSUFFICIENT_BALANCE troubleshooting page walks for every paid surface.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/carrier-billing:charge" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: dcb-7f3a2c19-20260909" \
  -d '{
  "phoneNumber": "+14155552671",
  "amount": 1.99,
  "currency": "EUR",
  "description": "Pro plan, one month",
  "merchantReference": "order_8472",
  "idempotencyKey": "dcb-7f3a2c19-20260909"
}'

Node.js

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/numbers/network-apis/carrier-billing:charge",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_TEST_API_KEY!,
      "Content-Type": "application/json",
      "Idempotency-Key": "dcb-7f3a2c19-20260909",
    },
    body: JSON.stringify({
      phoneNumber: "+14155552671",
      amount: 1.99,
      currency: "EUR",
      description: "Pro plan, one month",
      merchantReference: "order_8472",
      idempotencyKey: "dcb-7f3a2c19-20260909",
    }),
  },
);
console.log(await res.json());

{
  "data": {
    "paymentId": "pay-8f2c1d",
    "amountTransaction": {
      "paymentAmount": {
        "chargingInformation": {
          "amount": 1.99,
          "currency": "EUR",
          "description": "Pro plan, one month"
        },
        "chargingState": "processed"
      },
      "dccStatus": "success"
    }
  },
  "meta": {
    "request_id": "req_network_dcb_s15",
    "timestamp": "2026-09-09T12:00:15.000Z",
    "test_mode": true
  }
}

402

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "status": 402,
    "message": "Insufficient wallet balance to cover this charge"
  },
  "meta": {
    "request_id": "req_network_dcb_s15x",
    "timestamp": "2026-09-09T12:00:15.500Z"
  }
}

422 Over cap

{
  "error": {
    "code": "VALIDATION_ERROR",
    "status": 422,
    "message": "amount 250 exceeds the Carrier-Billing cap of 200 per transaction",
    "details": {
      "amount": 250,
      "currency": "EUR",
      "maxAmount": 200,
      "phoneNumber": "+1415555****"
    }
  },
  "meta": {
    "request_id": "req_network_dcb_s15c",
    "timestamp": "2026-09-09T12:00:15.750Z"
  }
}

Age Verification

POST /api/v1/numbers/network-apis/age-verification:verify

ageThreshold is an integer 13..120. The response carries the fail-closed ageVerified boolean plus the operator’s raw ageCheck marker (and identityMatchScore when the operator supplies it) for your audit trail — branch on ageVerified, never on the raw token.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/age-verification:verify" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+14155552671",
  "ageThreshold": 18
}'

Node.js

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/numbers/network-apis/age-verification:verify",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_TEST_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ phoneNumber: "+14155552671", ageThreshold: 18 }),
  },
);
console.log(await res.json());

{
  "data": {
    "ageVerified": true,
    "ageThreshold": 18,
    "ageCheck": "true",
    "identityMatchScore": 0.93
  },
  "meta": {
    "request_id": "req_network_age_s14",
    "timestamp": "2026-09-09T12:00:14.000Z",
    "test_mode": true
  }
}

Device Swap check

POST /api/v1/numbers/network-apis/device-swap:check

The handset-change sibling of SIM Swap: maxAge is the look-back in hours (1..2400, default 240). The response tells you whether the SIM started answering from a different IMEI inside the window, and when the most recent change happened.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/device-swap:check" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+14155552671",
  "maxAge": 240
}'

Node.js

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/numbers/network-apis/device-swap:check",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_TEST_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ phoneNumber: "+14155552671", maxAge: 240 }),
  },
);
console.log(await res.json());

{
  "data": {
    "swapped": true,
    "latestDeviceChange": "2026-09-08T04:15:00.000Z"
  },
  "meta": {
    "request_id": "req_network_ids_s16",
    "timestamp": "2026-09-09T12:00:16.000Z",
    "test_mode": true
  }
}

The worked pairs above carry both operations’ success envelopes; two reading rules survive the walkthrough:

Age Verification answers a verdict, never a birthdate. Anything but an explicit affirmative from the operator (a false, a missing field, an error shape leaking through a 2xx) resolves ageVerified: false — the fail-closed rule the buyer’s age gate must inherit.
Carrier Billing is the one operation on this page that moves money. The amount cap is server-side per deployment, and the 402 / 422 failure envelopes above are the two rejection shapes a production integrator must branch on before retrying.

Identity signals beyond the walkthroughs

POST /api/v1/numbers/network-apis/number-recycling:check

Tenure is itself a fraud signal: a recently recycled number may inherit compromises from the previous holder. Returns the recycled flag, days since the previous subscriber, and the previous-subscriber end date.

{
  "data": {
    "numberRecycled": true,
    "daysSincePreviousSubscriber": 12,
    "previousSubscriberEndDate": "2026-08-28"
  },
  "meta": {
    "request_id": "req_network_ids_s17",
    "timestamp": "2026-09-09T12:00:17.000Z",
    "test_mode": true
  }
}

POST /api/v1/numbers/network-apis/kyc-match:match

Returns per-attribute match results — true, false, or not_available per field, with an optional numeric score per attribute — never the underlying PII. Send the subscriber’s claimed identity alongside the number; the worked body below submits a full KYC document and gets one mostly-clean match back with a single mismatch to branch on.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/kyc-match:match" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+14155552671",
  "idDocument": { "type": "DRIVERS_LICENSE", "number": "D1234567" },
  "name": "Avery Quinn",
  "givenName": "Avery",
  "familyName": "Quinn",
  "birthdate": "1991-04-12",
  "email": "avery.quinn@example.com"
}'

Node.js

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/numbers/network-apis/kyc-match:match",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_TEST_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      phoneNumber: "+14155552671",
      idDocument: { type: "DRIVERS_LICENSE", number: "D1234567" },
      name: "Avery Quinn",
      givenName: "Avery",
      familyName: "Quinn",
      birthdate: "1991-04-12",
      email: "avery.quinn@example.com",
    }),
  },
);
console.log(await res.json());

{
  "data": {
    "idDocumentMatch": "true",
    "idDocumentScore": 93,
    "nameMatch": "true",
    "givenNameMatch": "true",
    "familyNameMatch": "false",
    "birthdateMatch": "not_available",
    "emailMatch": "true"
  },
  "meta": {
    "request_id": "req_network_ids_s18",
    "timestamp": "2026-09-09T12:00:18.000Z",
    "test_mode": true
  }
}

POST /api/v1/numbers/network-apis/sim-swap:retrieve-date

The raw-operator form of SIM Swap: the timestamp of the most recent SIM change, when a boolean is not enough. The worked body adds maxAge so a stale SIM answers swapped: false while still returning the raw date for your audit trail.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/sim-swap:retrieve-date" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+14155552671",
  "maxAge": 240
}'

Node.js

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/numbers/network-apis/sim-swap:retrieve-date",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_TEST_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ phoneNumber: "+14155552671", maxAge: 240 }),
  },
);
console.log(await res.json());

{
  "data": {
    "latestSimChange": "2026-09-08T04:15:00.000Z"
  },
  "meta": {
    "request_id": "req_network_ids_s19",
    "timestamp": "2026-09-09T12:00:19.000Z",
    "test_mode": true
  }
}

POST /api/v1/numbers/network-apis/identity:gate

The funnel-shaped variant of risk:score: same composite score, but the envelope carries the explicit decision plus review_or_block so a funnel can branch without re-interpreting the number.

{
  "data": {
    "decision": "review",
    "review_or_block": true,
    "risk_score": 60,
    "risk_level": "high",
    "reasons": ["sim_swap_recent", "roaming"],
    "signals_evaluated": ["simSwapped", "roaming"],
    "signals_unavailable": ["numberVerified"]
  },
  "meta": {
    "request_id": "req_network_ids_s20",
    "timestamp": "2026-09-09T12:00:20.000Z",
    "test_mode": true
  }
}

Connectivity insights, slices, and QoD reads

POST /api/v1/numbers/network-apis/connectivity-insights:check-network-quality

Each KPI is answered meets the application requirements or unable to meet the application requirements; the derived read adds the congestion verdict, the normalized congestionBand, and whether that verdict describes the current or a predicted horizon.

{
  "data": {
    "packetDelayBudget": "meets the application requirements",
    "targetMinDownstreamRate": "unable to meet the application requirements",
    "targetMinUpstreamRate": "meets the application requirements",
    "packetlossErrorRate": "meets the application requirements",
    "jitter": "meets the application requirements",
    "additionalKPIs": { "signalStrength": "good", "connectivityType": "4G" },
    "congestion": "congested",
    "congestionBand": "medium",
    "horizon": "current"
  },
  "meta": {
    "request_id": "req_network_ciq_s21",
    "timestamp": "2026-09-09T12:00:21.000Z",
    "test_mode": true
  }
}

POST /api/v1/numbers/network-apis/connectivity-insights/subscriptions

Creating a congestion-monitoring subscription returns the same operator-issued id / status / expiry shape as the SIM-swap and roaming variants. The read below resolves the same named example (ci-sub-01), so the create → read pair reads as one flow.

{
  "data": {
    "id": "ci-sub-01",
    "status": "ACTIVE",
    "startsAt": "2026-09-09T12:00:21.000Z",
    "expiresAt": "2026-09-16T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_network_ciq_s22",
    "timestamp": "2026-09-09T12:00:22.000Z",
    "test_mode": true
  }
}

GET /api/v1/numbers/network-apis/connectivity-insights/subscriptions/{subscriptionId}

Reading an existing subscription returns the same operator-issued state the create call established — the ci-sub-01 record above — plus the last congestion verdict the operator recorded for the watched number while the subscription is ACTIVE.

{
  "data": {
    "id": "ci-sub-01",
    "status": "ACTIVE",
    "startsAt": "2026-09-09T12:00:21.000Z",
    "expiresAt": "2026-09-16T12:00:00.000Z",
    "lastObservation": {
      "congestion": "congested",
      "congestionBand": "medium",
      "horizon": "current",
      "observedAt": "2026-09-09T12:00:23.000Z"
    }
  },
  "meta": {
    "request_id": "req_network_ciq_s23",
    "timestamp": "2026-09-09T12:00:23.000Z",
    "test_mode": true
  }
}

lastObservation mirrors the congestion payload the one-shot check-network-quality call returns (congestion + congestionBand + horizon); it is absent until the operator records a first verdict, and the webhook above remains the real-time feed. The webhook round trip. Create a Connectivity Insights subscription the same way you create a SIM-swap one: one POST carrying the watched number and your HTTPS sink. The worked body below enrolls the same +14155552671 used throughout this page and takes back the ci-sub-01 record above.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/connectivity-insights/subscriptions" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+14155552671",
  "notificationUrl": "https://your-app.example.com/webhooks/connectivity",
  "notificationAuthToken": "replace-with-a-long-random-bearer"
}'

While the subscription is ACTIVE, every congestion transition the operator detects is POSTed to your notificationUrl as a CloudEvent. notificationAuthToken comes back as the Authorization: Bearer header on each delivery — check it before you trust the body:

Webhook (POST to your notificationUrl)

{
  "id": "evt_01HZRX4K8P2Q7N3M6T9V2W5XCD",
  "source": "https://operator.example.com/connectivity-insights-subscriptions/v0",
  "type": "org.camaraproject.connectivity-insights-subscriptions.v0.congestion-changed",
  "specversion": "1.0",
  "datacontenttype": "application/json",
  "time": "2026-09-09T14:05:12.000Z",
  "data": {
    "subscriptionId": "ci-sub-01",
    "subscriptionDetail": {
      "device": { "phoneNumber": "+14155552671" },
      "congestion": "congested",
      "congestionBand": "high",
      "horizon": "current"
    }
  }
}

A minimal Express receiver rejects any delivery whose bearer token does not match the one you enrolled:

Node.js (Express receiver)

import express from "express";
import { timingSafeEqual } from "node:crypto";

const app = express();
app.post("/webhooks/connectivity", express.json(), (req, res) => {
  const expected = process.env.CONNECTIVITY_NOTIFICATION_TOKEN!;
  const got = (req.headers.authorization ?? "").replace(/^Bearer /, "");
  if (
    got.length !== expected.length ||
    !timingSafeEqual(Buffer.from(got), Buffer.from(expected))
  ) {
    return res.status(401).end();
  }
  const { type, data } = req.body;
  console.log(type, data.subscriptionDetail.congestion, data.subscriptionId);
  res.status(204).end();
});
app.listen(3000);

Acknowledge every delivery with a 2xx; anything else is retried. Stop the feed with DELETE /connectivity-insights/subscriptions/{subscriptionId} — the teardown answers 204 and the operator stops POSTing.

POST /api/v1/numbers/network-apis/network-slices

Booking returns the operator-issued reservation: bookingId plus its state (REQUESTED on creation, then ACTIVE once the operator confirms), echoed back with the window and device cap you booked.

{
  "data": {
    "bookingId": "slice-01",
    "state": "REQUESTED",
    "name": "match-day",
    "startTime": "2026-10-01T10:00:00.000Z",
    "endTime": "2026-10-01T22:00:00.000Z",
    "maxDevices": 5000
  },
  "meta": {
    "request_id": "req_network_nsq_s24",
    "timestamp": "2026-09-09T12:00:24.000Z",
    "test_mode": true
  }
}

GET /api/v1/numbers/network-apis/network-slices

The list read returns the array of reservations booked for this deployment — same booking objects, one per slice.

{
  "data": [
    {
      "bookingId": "slice-01",
      "state": "ACTIVE",
      "name": "match-day",
      "startTime": "2026-10-01T10:00:00.000Z",
      "endTime": "2026-10-01T22:00:00.000Z",
      "maxDevices": 5000
    }
  ],
  "meta": {
    "request_id": "req_network_nsq_s25",
    "timestamp": "2026-09-09T12:00:25.000Z",
    "test_mode": true
  }
}

GET /api/v1/numbers/network-apis/network-slices/{bookingId}

Reading one booking returns that booking’s current state — full window and device cap as booked — plus the live QoS descriptor the operator asserts for the slice.

{
  "data": {
    "bookingId": "slice-01",
    "state": "ACTIVE",
    "name": "match-day",
    "startTime": "2026-10-01T10:00:00.000Z",
    "endTime": "2026-10-01T22:00:00.000Z",
    "maxDevices": 5000,
    "qos": {
      "latencyMs": 20,
      "downstreamMbps": 50,
      "upstreamMbps": 10,
      "availability": "99.9"
    }
  },
  "meta": {
    "request_id": "req_network_nsq_s26",
    "timestamp": "2026-09-09T12:00:26.000Z",
    "test_mode": true
  }
}

The qos descriptor is the operator’s live assertion for the slice, not the profile you requested at booking — treat a mismatch against your booking as the operator’s current offer for this reservation.

GET /api/v1/numbers/network-apis/qod-sessions/{sessionId}

Polling a session returns its full record — the status the create call issued (REQUESTED until the operator confirms AVAILABLE or UNAVAILABLE), the profile, the lifetime window, and the measured throughput while the bearer is up.

{
  "data": {
    "sessionId": "sess_6f8a0c2d4e",
    "qosProfile": "QOS_L",
    "qosStatus": "AVAILABLE",
    "startedAt": "2026-09-09T12:00:07.000Z",
    "expiresAt": "2026-09-09T13:00:07.000Z",
    "duration": 3600,
    "throughput": {
      "downstreamMbps": 48.2,
      "upstreamMbps": 9.6
    }
  },
  "meta": {
    "request_id": "req_network_qod_s27",
    "timestamp": "2026-09-09T12:00:27.000Z",
    "test_mode": true
  }
}

throughput appears once qosStatus reaches AVAILABLE; while the session is still REQUESTED the record carries the status, profile, and window only.

POST /api/v1/numbers/network-apis/qod-sessions/{sessionId}/extend

Extending returns the same session record with the widened duration and pushed-back expiresAt.

{
  "data": {
    "sessionId": "sess_6f8a0c2d4e",
    "qosStatus": "AVAILABLE",
    "expiresAt": "2026-09-09T14:00:07.000Z",
    "duration": 7200
  },
  "meta": {
    "request_id": "req_network_qod_s28",
    "timestamp": "2026-09-09T12:00:28.000Z",
    "test_mode": true
  }
}

9. Python goose — SDK escape hatch for a one-off read

The typed SDKs mirror the most-used operations; for the long tail, every SDK exposes a generic request() escape hatch that sends any path on this page with the client’s auth already applied. This goose client polls device-status:reachability for the worked number:

Python

import os
from goose import Goose

client = Goose(api_key=os.environ["ORBIT_API_KEY"])

res = client.request(
    "POST",
    "/api/v1/numbers/network-apis/device-status:reachability",
    json={"phoneNumber": "+14155552671"},
)
print(res.json())
# {'data': {'reachabilityStatus': 'CONNECTED_DATA'}, 'meta': {'request_id': 'req_network_dsr_py1', 'timestamp': '2026-09-09T12:00:40.000Z', 'test_mode': True}}

The same call through cURL, for reference:

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/device-status:reachability" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+14155552671"
}'

200

{
  "data": {
    "reachabilityStatus": "CONNECTED_DATA"
  },
  "meta": {
    "request_id": "req_network_dsr_py1",
    "timestamp": "2026-09-09T12:00:40.000Z",
    "test_mode": true
  }
}

10. Caller-correctable 4xx — operator rejection, expired subscription, QoD conflict

The 422 / 502 / 503 table above covers validation and operator-availability failures. Three more 4xx shapes are caller-correctable and worth branching on explicitly: an operation your operator deployment does not offer, a subscription you keep using past expiry, and a QoD session you try to create twice. operator_not_supported — the deployment’s operator does not offer this CAMARA service (distinct from the no-operator 503): the service is configured but not served. Reroute to a fallback or gate the feature until the operator enrollment covers it.

422

{
  "error": {
    "code": "operator_not_supported",
    "status": 422,
    "message": "The connected operator does not offer Device Location for this deployment"
  },
  "meta": {
    "request_id": "req_network_err_s41",
    "timestamp": "2026-09-09T12:00:41.000Z"
  }
}

subscription_not_found — a read or delete against a subscriptionId, sessionId, or bookingId the operator no longer knows (never enrolled on this deployment, already deleted, or purged after expiry). Re-read your create response for the id that call returned; do not cache ids across deployments.

404

{
  "error": {
    "code": "subscription_not_found",
    "status": 404,
    "message": "No subscription with id sub_00000000000000000000 for this deployment",
    "details": {
      "subscriptionId": "sub_00000000000000000000"
    }
  },
  "meta": {
    "request_id": "req_network_err_s44",
    "timestamp": "2026-09-17T08:13:02.000Z"
  }
}

subscription_expired — a read or delete against a subscription whose expiresAt has passed. Renew by creating a fresh subscription and retry once with the new id rather than reusing the stale one.

410

{
  "error": {
    "code": "subscription_expired",
    "status": 410,
    "message": "Subscription sub_1b3d5f7a9c2e4g6h8i0j expired at 2026-09-16T12:00:00.000Z",
    "details": {
      "subscriptionId": "sub_1b3d5f7a9c2e4g6h8i0j",
      "expiresAt": "2026-09-16T12:00:00.000Z"
    }
  },
  "meta": {
    "request_id": "req_network_err_s42",
    "timestamp": "2026-09-17T08:12:44.000Z"
  }
}

qod_session_conflict — one active QoD session per device and application server. Either extend the live session (POST .../extend) or DELETE it before creating a replacement.

409

{
  "error": {
    "code": "qod_session_conflict",
    "status": 409,
    "message": "An active QoD session already exists for this device and application server",
    "details": {
      "sessionId": "sess_6f8a0c2d4e",
      "qosStatus": "AVAILABLE",
      "expiresAt": "2026-09-09T13:00:00.000Z"
    }
  },
  "meta": {
    "request_id": "req_network_err_s43",
    "timestamp": "2026-09-09T12:00:43.000Z"
  }
}

Code	Status	Corrective action
`operator_not_supported`	422	The operator deployment does not offer this CAMARA service — gate the feature or fall back until enrollment covers it
`subscription_not_found`	404	Re-read the id from your create response — never cache ids across deployments
`subscription_expired`	410	Create a fresh subscription and retry with the new id
`qod_session_conflict`	409	Extend the live session or `DELETE` it, then create

Polling a subscription. Prefer the CloudEvent webhooks — polling is the fallback when your sink missed a delivery. A poll loop treats 200 as “still live unless REVOKED”, 404 as “gone, stop”, and 410 as “renew”:

cURL (poll until terminal)

ID="sub_1b3d5f7a9c2e4g6h8i0j"
URL="https://api.orbit.devotel.io/api/v1/numbers/network-apis/sim-swap/subscriptions/$ID"
while true; do
  code=$(curl -s -o /tmp/sub.json -w "%{http_code}" -X GET "$URL" \
    -H "X-API-Key: dv_live_sk_your_key_here")
  case "$code" in
    200) grep -q '"status": "REVOKED"' /tmp/sub.json && echo "revoked — re-enroll" && break ;;
    404) echo "unknown id — stop polling, re-enroll"; break ;;
    410) echo "expired — create a fresh subscription"; break ;;
    *)   echo "transient $code — back off";;
  esac
  sleep 30
done

The same loop works for device-roaming-status/subscriptions/{subscriptionId} and connectivity-insights/subscriptions/{subscriptionId} by swapping the path; QoD sessions and slice bookings terminate on qosStatus/state instead of status.

Subscription state reads and teardowns

Every subscription read on this page answers the same lifecycle in status: ACTIVE while the operator monitors the number, EXPIRED once expiresAt has passed (reads then answer the subscription_expired 410 below), and REVOKED when the operator withdrew the subscription server-side before expiry — treats it as terminal, re-enroll with a fresh POST /subscriptions rather than polling.

POST /api/v1/numbers/network-apis/device-roaming-status/subscriptions

Creating a roaming-monitoring subscription returns the same id / status / expiry shape as the SIM-swap variant; the operator then POSTs roaming-on / roaming-off CloudEvents to your notificationUrl.

{
  "data": {
    "id": "roam-sub-01",
    "status": "ACTIVE",
    "startsAt": "2026-09-09T12:00:29.000Z",
    "expiresAt": "2026-09-16T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_network_sub_s29",
    "timestamp": "2026-09-09T12:00:29.000Z",
    "test_mode": true
  }
}

GET /api/v1/numbers/network-apis/sim-swap/subscriptions/{subscriptionId}

Reading a SIM-swap subscription’s current state — same envelope the create call established, plus the masked recency fact CAMARA privacy rules allow on a read.

{
  "data": {
    "id": "sub_1b3d5f7a9c2e4g6h8i0j",
    "status": "ACTIVE",
    "startsAt": "2026-09-09T12:00:08.000Z",
    "expiresAt": "2026-09-16T12:00:00.000Z",
    "lastSimSwapDate": "2025-11-03T00:00:00.000Z",
    "lastSimSwapDateMasked": true
  },
  "meta": {
    "request_id": "req_network_sub_s30",
    "timestamp": "2026-09-09T12:00:30.000Z",
    "test_mode": true
  }
}

Under CAMARA privacy rules a subscription read never carries a fresh exact swap timestamp: lastSimSwapDate is truncated to day precision (T00:00:00.000Z) and lastSimSwapDateMasked is always true on this read, so you can rank the subscription’s recency without the operator exposing a privacy-sensitive exact instant. When the last swap predates the operator’s retention window, both fields are omitted; for the precise date your fraud flow wants, call POST /sim-swap:retrieve-date with the subject for each check.

GET /api/v1/numbers/network-apis/device-roaming-status/subscriptions/{subscriptionId}

Reading a roaming subscription’s current state — same envelope the create call established, plus the last roaming assertion the operator recorded for the watched number.

{
  "data": {
    "id": "roam-sub-01",
    "status": "ACTIVE",
    "startsAt": "2026-09-09T12:00:29.000Z",
    "expiresAt": "2026-09-16T12:00:00.000Z",
    "roaming": true,
    "countryCode": "DE",
    "countryName": "Germany",
    "checkedAt": "2026-09-09T12:00:31.000Z"
  },
  "meta": {
    "request_id": "req_network_sub_s31",
    "timestamp": "2026-09-09T12:00:31.000Z",
    "test_mode": true
  }
}

roaming/countryCode/countryName carry the same visited-country answer the one-shot device-roaming-status:retrieve returns — checkedAt stamps when the operator last asserted it. When the device is home, roaming is false and the country fields are omitted.

Subscription, session, slice, and announcement teardowns — 204 No Content

DELETE /api/v1/numbers/network-apis/sim-swap/subscriptions/{subscriptionId}

Six teardowns complete the page’s thirty-eight operations — the unwinds paired with the creates, bookings, and announcements walked above: this SIM-swap subscription delete, that of DELETE /api/v1/numbers/network-apis/device-roaming-status/subscriptions/{subscriptionId}, that of DELETE /api/v1/numbers/network-apis/connectivity-insights/subscriptions/{subscriptionId}, that of DELETE /api/v1/numbers/network-apis/qod-sessions/{sessionId}, that of DELETE /api/v1/numbers/network-apis/network-slices/{bookingId}, and that of DELETE /api/v1/numbers/network-apis/internet-access/announcements. All six answer 204 No Content with no body — the 2xx status alone confirms the operator stopped the subscription, released the session, freed the slice, or withdrew the prefix; a GET on the same id afterward answers 404. The one body in the family. Withdrawing a prefix announcement is the exception: it carries the same fenced { prefix, asn, proofOfOwnershipToken } body its POST create takes — the operator honors a withdrawal only against a live enrollment fence, so mirror your announce call verbatim:

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/numbers/network-apis/internet-access/announcements" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "prefix": "192.0.2.0/24",
  "asn": 65552,
  "proofOfOwnershipToken": "replace-with-the-token-the-operator-issued-at-enrollment"
}'

Node.js

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/numbers/network-apis/internet-access/announcements",
  {
    method: "DELETE",
    headers: {
      "X-API-Key": process.env.ORBIT_TEST_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      prefix: "192.0.2.0/24",
      asn: 65552,
      proofOfOwnershipToken:
        "replace-with-the-token-the-operator-issued-at-enrollment",
    }),
  },
);
console.log(res.status); // 204 — withdrawn; re-read with the GET list call

// Empty body — `204 No Content` confirms the withdrawal; the operator drops
// the prefix from the tenant's ACTIVE set. Confirm with the GET list call.

Error envelope — operator-side rejection

An off-spec body (a non-E.164 number, an out-of-range radius, a missing subject field) is rejected before any operator sees it, so the 422 with VALIDATION_ERROR costs you nothing and carries the offending field in error.details.issues. When the operator itself rejects the request (an unknown subscriber, an out-of-range window) the rejection is mapped to a caller-correctable 422 with the operator’s own code preserved in details.upstream_code; when the operator cannot be reached at all, the call surfaces as a 502 UPSTREAM_ERROR rather than a false result. Sandbox keys never reach an operator, so you see the upstream shapes only with a live key.

422

{
  "error": {
    "code": "VALIDATION_ERROR",
    "status": 422,
    "message": "CAMARA: the subscriber is unknown to the operator",
    "details": {
      "upstream_code": "NOT_FOUND",
      "phoneNumber": "+1415555****"
    }
  },
  "meta": {
    "request_id": "req_network_err_s10",
    "timestamp": "2026-09-09T12:00:09.000Z"
  }
}

The phoneNumber in every error detail is masked — a rejection never echoes the full E.164 subject back.

Error envelope — 503 fails closed with no operator

Call any live signal dip before a CAMARA operator is enrolled for the deployment and the route fails closed: no signal is fabricated, no low-risk answer is invented, and the caller gets a single, explicit 503. Every operation on this page raises the identical body, so a GET /status-gated client should treat enabled: false as “this is what any call would return”.

503

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "status": 503,
    "message": "GSMA/CAMARA network APIs are not enabled for this deployment — no operator credentials configured."
  },
  "meta": {
    "request_id": "req_network_err_s34",
    "timestamp": "2026-09-09T12:00:34.000Z"
  }
}

Class	Status	Code	When you will hit it
Malformed or incomplete body	422	`VALIDATION_ERROR`	Non-E.164 subject, missing `phoneNumber`/`hashedPhoneNumber`, a `radius` outside 2,000..200,000, `maxAge` outside the operation’s range
Operator-side rejection	422	`VALIDATION_ERROR` (+ `details.upstream_code`)	Unknown subscriber, an out-of-range window the operator refuses, a stale fencing token on a prefix announcement
No operator configured	503	`SERVICE_UNAVAILABLE`	The call fails closed with no live CAMARA operator on the deployment — the headers above carry the exact body; use a `dv_test_sk_*` sandbox key (or the `GET /status` gate) until an operator is enrolled
Operator unreachable	502	`UPSTREAM_ERROR`	Network fault against the operator endpoint — never returned as a false low-risk result
Unreadable subscription/session id	404	`NOT_FOUND`	The operator no longer knows the subscription or booking id you passed

Auth failure — missing or invalid key

Every operation on this page first passes the platform’s API-key gate. A missing, malformed, or revoked X-API-Key fails with a 401 before the network-apis layer runs: no operator contact, no credits deducted. This is the client-credentials failure mode for server-to-server callers — confirm the header carries the raw key (no Bearer wrapper) and the right prefix for the environment (dv_test_sk_* for sandbox, dv_live_sk_* for live).

401

{
  "error": {
    "code": "UNAUTHORIZED",
    "status": 401,
    "message": "Missing or invalid API key"
  },
  "meta": {
    "request_id": "req_network_err_s33",
    "timestamp": "2026-09-09T12:00:33.000Z"
  }
}

The pre-send check a high-value transaction actually runs, end to end: prove the device answers, read where it roams, enroll continuous roaming monitoring, and book the QoS bearer when the “send” is a live session rather than a message. Which signals to combine for account-takeover vs. delivery-risk decisions is the strategy side, covered in Network signals with GSMA Open Gateway; this section is the wire format, with every response body shown as the sandbox returns it.

GSMA Open Gateway surface, three flows

The thirty-eight operations on this page do three jobs:

Prove the subscriber — Number Verification, SIM Swap, KYC Match, Age Verification: is this person who they claim, right now?
Place the device — Device Status reachability, Device Roaming Status, Device Location: where is it, and can it hear from you?
Shape the bearer — Quality-on-Demand sessions and network slices: give the traffic the latency or throughput it needs while the session lasts.

Every call sends your Orbit API key in X-API-Key and returns the same { data, meta } envelope. A dv_test_sk_* key answers from the sandbox with meta.test_mode: true and never contacts an operator, so you can wire and replay the whole sequence below at zero charge.

Number Verification silent auth

POST /api/v1/numbers/network-apis/number-verification:verify

Send exactly one subject: phoneNumber in E.164, or its SHA-256 hashedPhoneNumber. When the device has already completed the operator’s three-legged redirect, add the accessToken it brought back — the operator then matches the redirected session against the MSISDN it sees on the bearer. That redirect-then-confirm pair is the silent-auth alternative to an SMS OTP: the device proves possession over the operator flow, your backend confirms with this call.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/number-verification:verify" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+14155552671"
}'

Node.js

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/numbers/network-apis/number-verification:verify",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_TEST_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ phoneNumber: "+14155552671" }),
  },
);
console.log(await res.json());

{
  "data": {
    "devicePhoneNumberVerified": true
  },
  "meta": {
    "request_id": "req_network_nva_w1",
    "timestamp": "2026-10-15T09:00:00.000Z",
    "test_mode": true
  }
}

true is the network asserting possession of the number. false is no assertion, not proof of absence — fall back to OTP rather than rejecting the user.

SIM-swap gate

POST /api/v1/numbers/network-apis/sim-swap:check

First gate before accepting a sensitive session: was the SIM behind this number swapped inside your look-back window? maxAge is hours (1..2400, default 240).

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/sim-swap:check" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+14155552671",
  "maxAge": 240
}'

Node.js

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/numbers/network-apis/sim-swap:check",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_TEST_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ phoneNumber: "+14155552671", maxAge: 240 }),
  },
);
console.log(await res.json());

{
  "data": {
    "swapped": false
  },
  "meta": {
    "request_id": "req_network_ssc_w2",
    "timestamp": "2026-10-15T09:00:01.000Z",
    "test_mode": true
  }
}

When you need the raw fact instead of the boolean, retrieve the operator’s last SIM-change timestamp:

POST /api/v1/numbers/network-apis/sim-swap:retrieve-date

{
  "data": {
    "latestSimChange": "2026-09-08T04:15:00.000Z"
  },
  "meta": {
    "request_id": "req_network_ssr_w3",
    "timestamp": "2026-10-15T09:00:02.000Z",
    "test_mode": true
  }
}

For continuous monitoring, enroll the number once and let the operator push the event. Create returns the operator-issued id, status, and expiry; the read on that id answers the same record while the subscription is live:

POST /api/v1/numbers/network-apis/sim-swap/subscriptions

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/sim-swap/subscriptions" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+14155552671",
  "notificationUrl": "https://your-app.example.com/webhooks/camara",
  "notificationAuthToken": "replace-with-a-long-random-bearer"
}'

{
  "data": {
    "id": "sub_1b3d5f7a9c2e4g6h8i0j",
    "status": "ACTIVE",
    "startsAt": "2026-10-15T09:00:03.000Z",
    "expiresAt": "2026-10-22T09:00:03.000Z"
  },
  "meta": {
    "request_id": "req_network_sss_w4",
    "timestamp": "2026-10-15T09:00:03.000Z",
    "test_mode": true
  }
}

GET /api/v1/numbers/network-apis/sim-swap/subscriptions/{subscriptionId}

{
  "data": {
    "id": "sub_1b3d5f7a9c2e4g6h8i0j",
    "status": "ACTIVE",
    "startsAt": "2026-10-15T09:00:03.000Z",
    "expiresAt": "2026-10-22T09:00:03.000Z"
  },
  "meta": {
    "request_id": "req_network_sss_w5",
    "timestamp": "2026-10-15T09:00:04.000Z",
    "test_mode": true
  }
}

The moment a swap occurs the operator POSTs a CloudEvent to your notificationUrl; the delivery envelope and the bearer-token check for your receiver are shown in section 2b above. Stop the feed with DELETE on the same id (204, no body).

Roaming + QoD for high-value sends

Confirm the device can hear from you, then read where it sits. A NOT_CONNECTED reachability read before an OTP send is a wasted-send gate; a roaming read that puts the device in a country you do not serve is a funnel gate.

POST /api/v1/numbers/network-apis/device-status:reachability

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/device-status:reachability" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+14155552671"
}'

Node.js

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/numbers/network-apis/device-status:reachability",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_TEST_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ phoneNumber: "+14155552671" }),
  },
);
console.log(await res.json());

{
  "data": {
    "reachabilityStatus": "CONNECTED_DATA"
  },
  "meta": {
    "request_id": "req_network_dsr_w6",
    "timestamp": "2026-10-15T09:00:05.000Z",
    "test_mode": true
  }
}

The roaming read takes the same body and answers one verdict — roaming plus the visited country when the operator supplies it:

POST /api/v1/numbers/network-apis/device-roaming-status:retrieve

{
  "data": {
    "roaming": true,
    "countryCode": "44",
    "countryName": "United Kingdom"
  },
  "meta": {
    "request_id": "req_network_rss_w7",
    "timestamp": "2026-10-15T09:00:06.000Z",
    "test_mode": true
  }
}

A one-off read leaves you polling. Subscribe instead, and the operator POSTs roaming-on / roaming-off CloudEvents to your notificationUrl as the device crosses borders:

POST /api/v1/numbers/network-apis/device-roaming-status/subscriptions

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/device-roaming-status/subscriptions" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+14155552671",
  "notificationUrl": "https://your-app.example.com/webhooks/camara",
  "notificationAuthToken": "replace-with-a-long-random-bearer"
}'

{
  "data": {
    "id": "roam-sub-01",
    "status": "ACTIVE",
    "startsAt": "2026-10-15T09:00:07.000Z",
    "expiresAt": "2026-10-22T09:00:07.000Z"
  },
  "meta": {
    "request_id": "req_network_rss_w8",
    "timestamp": "2026-10-15T09:00:07.000Z",
    "test_mode": true
  }
}

GET /api/v1/numbers/network-apis/device-roaming-status/subscriptions/{subscriptionId} reads the same record back; DELETE on the id stops the feed with 204. When the high-value send is a live session — a video consult, a cloud-gaming stream — book the QoS bearer instead of trusting the default one. qosProfile names an offering the operator publishes for your deployment (the worked deployment’s low-latency profile is QOS_L); duration is seconds, 60..86400.

POST /api/v1/numbers/network-apis/qod-sessions

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/qod-sessions" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "device": { "phoneNumber": "+14155552671" },
  "applicationServer": { "ipv4Address": "192.0.2.10" },
  "qosProfile": "QOS_L",
  "duration": 3600
}'

Node.js

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/numbers/network-apis/qod-sessions",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_TEST_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      device: { phoneNumber: "+14155552671" },
      applicationServer: { ipv4Address: "192.0.2.10" },
      qosProfile: "QOS_L",
      duration: 3600,
    }),
  },
);
console.log(await res.json());

{
  "data": {
    "sessionId": "sess_6f8a0c2d4e",
    "qosStatus": "REQUESTED",
    "expiresAt": "2026-10-15T10:00:08.000Z"
  },
  "meta": {
    "request_id": "req_network_qod_w9",
    "timestamp": "2026-10-15T09:00:08.000Z",
    "test_mode": true
  }
}

qosStatus moves REQUESTED → AVAILABLE (or UNAVAILABLE) once the operator confirms; poll with GET /qod-sessions/{sessionId}, add time with POST .../extend, release early with DELETE (204). The full extend/delete round trip is in section 7.

Tenant prefix announcements

If your tenant brings its own IP space, announce the prefix toward the Internet and keep the failover audit feed on hand. The create body carries the fence — the proof-of-ownership token the operator issued at enrollment — and your owning ASN:

POST /api/v1/numbers/network-apis/internet-access/announcements

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/internet-access/announcements" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "prefix": "192.0.2.0/24",
  "asn": 65552,
  "proofOfOwnershipToken": "replace-with-the-token-the-operator-issued-at-enrollment"
}'

{
  "data": {
    "prefix": "192.0.2.0/24",
    "asn": 65552,
    "state": "ACTIVE"
  },
  "meta": {
    "request_id": "req_network_byo_w10",
    "timestamp": "2026-10-15T09:00:10.000Z",
    "test_mode": true
  }
}

The failover feed is a read expressed as POST with query filters (prefix restricts to one announced CIDR, limit 1..500 caps the page) — it answers who announced or withdrew which prefix, most recent first:

POST /api/v1/numbers/network-apis/internet-access/failover-events

{
  "data": {
    "events": [
      {
        "type": "announcement",
        "prefix": "192.0.2.0/24",
        "asn": 65552,
        "at": "2026-10-14T09:11:00.000Z"
      }
    ],
    "next": null
  },
  "meta": {
    "request_id": "req_network_byo_w11",
    "timestamp": "2026-10-15T09:00:11.000Z",
    "test_mode": true
  }
}

Withdraw with DELETE /internet-access/announcements and the same fenced body; re-read the list to confirm the prefix left your ACTIVE set. The strategy for combining these signals before a high-value send — which dips gate, which step up, which merely log — lives in Network signals with GSMA Open Gateway.

API Reference

All Endpoints

Worked request and response samples

Authentication, per-service subscription, and the response envelope

The 38 operations in five families

1. Number Verification (Silent Auth)

2. SIM Swap check

2b. SIM Swap subscription — create + the webhook it triggers

3. Device Location verification

4. Device reachability + roaming status

5. Unified Identity Risk score

6. Scam Signal assessment

7. Quality-on-Demand session

8. Continuous monitoring — subscription round trip

Remaining envelopes by family

Operator status — is a live operator configured?

Bring-your-own-prefix routing — announcements and failover

Carrier billing, age verification, and device swap — request + response pairs

Carrier Billing charge

Age Verification

Device Swap check

Identity signals beyond the walkthroughs

Connectivity insights, slices, and QoD reads

9. Python goose — SDK escape hatch for a one-off read

10. Caller-correctable 4xx — operator rejection, expired subscription, QoD conflict

Subscription state reads and teardowns

Subscription, session, slice, and announcement teardowns — 204 No Content

Error envelope — operator-side rejection

Error envelope — 503 fails closed with no operator

Auth failure — missing or invalid key

GSMA Open Gateway surface, three flows

Number Verification silent auth

SIM-swap gate

Roaming + QoD for high-value sends

Tenant prefix announcements

​Worked request and response samples

​Authentication, per-service subscription, and the response envelope

​The 38 operations in five families

​1. Number Verification (Silent Auth)

​2. SIM Swap check

​2b. SIM Swap subscription — create + the webhook it triggers

​3. Device Location verification

​4. Device reachability + roaming status

​5. Unified Identity Risk score

​6. Scam Signal assessment

​7. Quality-on-Demand session

​8. Continuous monitoring — subscription round trip

​Remaining envelopes by family

​Operator status — is a live operator configured?

​Bring-your-own-prefix routing — announcements and failover

​Carrier billing, age verification, and device swap — request + response pairs

​Carrier Billing charge

​Age Verification

​Device Swap check

​Identity signals beyond the walkthroughs

​Connectivity insights, slices, and QoD reads

​9. Python goose — SDK escape hatch for a one-off read

​10. Caller-correctable 4xx — operator rejection, expired subscription, QoD conflict

​Subscription state reads and teardowns

​Subscription, session, slice, and announcement teardowns — 204 No Content

​Error envelope — operator-side rejection

​Error envelope — 503 fails closed with no operator

​Auth failure — missing or invalid key

​Worked sequence: confirm reachability, then subscribe to roaming events

​GSMA Open Gateway surface, three flows

​Number Verification silent auth

​SIM-swap gate

​Roaming + QoD for high-value sends

​Tenant prefix announcements

Worked request and response samples

Authentication, per-service subscription, and the response envelope

The 38 operations in five families

1. Number Verification (Silent Auth)

2. SIM Swap check

2b. SIM Swap subscription — create + the webhook it triggers

3. Device Location verification

4. Device reachability + roaming status

5. Unified Identity Risk score

6. Scam Signal assessment

7. Quality-on-Demand session

8. Continuous monitoring — subscription round trip

Remaining envelopes by family

Operator status — is a live operator configured?

Bring-your-own-prefix routing — announcements and failover

Carrier billing, age verification, and device swap — request + response pairs

Carrier Billing charge

Age Verification

Device Swap check

Identity signals beyond the walkthroughs

Connectivity insights, slices, and QoD reads

9. Python goose — SDK escape hatch for a one-off read

10. Caller-correctable 4xx — operator rejection, expired subscription, QoD conflict

Subscription state reads and teardowns

Subscription, session, slice, and announcement teardowns — 204 No Content

Error envelope — operator-side rejection

Error envelope — 503 fails closed with no operator

Auth failure — missing or invalid key

Worked sequence: confirm reachability, then subscribe to roaming events

GSMA Open Gateway surface, three flows

Number Verification silent auth

SIM-swap gate

Roaming + QoD for high-value sends

Tenant prefix announcements