Network APIs

Tap directly into the mobile operator network for silent, no-OTP identity and fraud signals. These endpoints wrap the GSMA Open Gateway / CAMARA APIs behind a single, tenant-scoped surface so you can verify a number, detect a recent SIM swap, confirm a device’s location or reachability, match KYC attributes, charge the operator bill, and fuse it all into one risk verdict — without ever sending a message to the subscriber. Base path: /api/v1/numbers/network-apis

The upstream integration is gated on operator credentials per deployment. When no operator is configured every endpoint fails closed — it returns 503 SERVICE_UNAVAILABLE rather than fabricating an identity result. Call Operator status first to check whether the surface is live.

All requests are authenticated with your API key and rate-limited on the standard read/write buckets. Phone numbers are E.164 (e.g. +14155550100).

Using the SDKs

Prefer the typed client, but this page’s endpoint has no helper yet — the generic request() keeps auth/retries and the { data, meta } envelope identical:

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

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

const { data } = await orbit.request<unknown>(
  "GET",
  "/numbers/network-apis"
);

Python (same call via the SDK’s escape hatch):

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("GET", "/numbers/network-apis")

The Python SDK is core-scope — it wraps the 8 core resources (messaging, voice, contacts, campaigns, verify, numbers) and reaches everything else through the generic client.request() escape hatch above. See the Python SDK. Raw curl in the body of this page works identically. Full SDK index at SDK quickstart.

Operator status

GET /api/v1/numbers/network-apis/status Report whether GSMA/CAMARA operator credentials are configured for this deployment. Returns a boolean only — never a secret.

curl "https://api.orbit.devotel.io/api/v1/numbers/network-apis/status" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{ "data": { "enabled": true }, "meta": { "request_id": "req_naas_001" } }

Number Verification (Silent Auth)

POST /api/v1/numbers/network-apis/number-verification:verify Verify a network-asserted MSISDN — the silent alternative to an SMS OTP. Fails closed: anything that is not an explicit network-confirmed match resolves to devicePhoneNumberVerified: false.

string

E.164 number to verify. Provide exactly one of phoneNumber or hashedPhoneNumber.

string

SHA-256 hash of the E.164 number (privacy-preserving variant).

string

Device-bound access token from the 3-legged CIBA / auth-code flow completed over the cellular data bearer. When present it proves device possession.

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

When you hold only the SHA-256 hash of the number — for example inside a privacy-preserving pipeline — send hashedPhoneNumber instead:

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

{ "data": { "devicePhoneNumberVerified": true }, "meta": { "request_id": "req_naas_002" } }

SIM Swap

Check

POST /api/v1/numbers/network-apis/sim-swap:check Was the SIM behind a number swapped within the look-back window? A recent swap is a strong account-takeover signal.

string

required

E.164 number to check.

integer

default:"240"

Look-back window in hours (range 1–2400). Default 240 (10 days).

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

{ "data": { "swapped": false }, "meta": { "request_id": "req_naas_003" } }

Retrieve date

POST /api/v1/numbers/network-apis/sim-swap:retrieve-date Return the timestamp of the most recent SIM change, for callers that want the raw date rather than a boolean.

string

required

E.164 number to look up.

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

{ "data": { "latestSimChange": "2026-05-12T08:31:00Z" }, "meta": { "request_id": "req_naas_004" } }

Subscriptions (continuous monitoring)

Poll instead where you can, subscribe where you must — enroll a number into continuous SIM-swap monitoring and the operator pushes a CloudEvent to your HTTPS webhook the instant the SIM is swapped. Create a subscription (POST /api/v1/numbers/network-apis/sim-swap/subscriptions):

string

required

E.164 number to monitor.

string

required

HTTPS webhook the operator POSTs swap notifications to.

string

Bearer token the operator presents on each callback, so you can authenticate the inbound notification.

string

RFC-3339 UTC expiry. Omit for an open-ended subscription you tear down with DELETE.

integer

Stop after this many delivered events (1–1000).

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/sim-swap/subscriptions" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+14155550100",
    "notificationUrl": "https://your-app.example/hooks/sim-swap",
    "notificationAuthToken": "shared-webhook-secret"
  }'

{ "data": { "id": "sub_abc123", "status": "ACTIVE", "expiresAt": "2026-12-31T00:00:00Z" }, "meta": { "request_id": "req_naas_004s" } }

Read one subscription (GET /api/v1/numbers/network-apis/sim-swap/subscriptions/{subscriptionId}):

curl "https://api.orbit.devotel.io/api/v1/numbers/network-apis/sim-swap/subscriptions/sub_abc123" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{ "data": { "id": "sub_abc123", "status": "ACTIVE" }, "meta": { "request_id": "req_naas_004g" } }

Cancel a subscription (DELETE /api/v1/numbers/network-apis/sim-swap/subscriptions/{subscriptionId}):

curl -X DELETE "https://api.orbit.devotel.io/api/v1/numbers/network-apis/sim-swap/subscriptions/sub_abc123" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Returns 204 No Content — the operator stops delivering swap notifications.

Device Swap

POST /api/v1/numbers/network-apis/device-swap:check The account-takeover sibling of SIM Swap: was the SIM behind a number moved to a different handset (an IMEI change) within the look-back window? A subscriber whose card suddenly answers from a new device is a strong takeover corroborator — distinct from a fresh SIM.

string

required

E.164 number to check.

integer

default:"240"

Look-back window in hours (range 1–2400). Default 240.

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

{ "data": { "swapped": false }, "meta": { "request_id": "req_naas_004b" } }

Device Roaming Status

POST /api/v1/numbers/network-apis/device-roaming-status:retrieve Surface the operator’s network-asserted roaming state for a device — a SIM answering in an unexpected country is a takeover and fraud corroborator you can fuse into your own decisioning.

string

required

E.164 number of the device.

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

{ "data": { "roaming": true }, "meta": { "request_id": "req_naas_004c" } }

Continuous monitoring: enroll the number into roaming on/off notifications via POST /api/v1/numbers/network-apis/device-roaming-status/subscriptions, then read or cancel with the matching GET / DELETE on /device-roaming-status/subscriptions/{subscriptionId}. The request and lifecycle shapes are identical to the SIM Swap subscriptions above.

KYC Match

POST /api/v1/numbers/network-apis/kyc-match:match Match caller-supplied identity attributes against the operator’s KYC records. Returns per-attribute match results — never the underlying PII.

string

required

E.164 number whose KYC record to match against.

string

Full name to match.

string

Given (first) name.

string

Family (last) name.

string

Date of birth (ISO YYYY-MM-DD).

string

National ID / document number.

string

Email address to match.

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/kyc-match:match" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+14155550100",
    "name": "Ana Doe",
    "birthdate": "1985-03-17"
  }'

{ "data": { "nameMatch": "true", "birthdateMatch": "true" }, "meta": { "request_id": "req_naas_005" } }

Tenant-owned control: only send the identity attributes your tenant’s lawful KYC basis covers. The operator returns per-attribute match tokens and never the underlying PII, so no subscriber data is exposed beyond what you already hold.

Device Location Verification

POST /api/v1/numbers/network-apis/device-location:verify Confirm whether a device is within a claimed geofence (a circle) without revealing its coordinates.

string

required

E.164 number of the device.

number

required

Geofence centre latitude (WGS-84, -90–90).

number

required

Geofence centre longitude (WGS-84, -180–180).

integer

required

Geofence radius in metres (2000–200000).

integer

Max age in seconds of the location fix the operator may use (60–3600).

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

{ "data": { "verificationResult": "TRUE", "matchRate": 95 }, "meta": { "request_id": "req_naas_006" } }

verificationResult is one of TRUE, FALSE, PARTIAL, UNKNOWN.

Device Status reachability

POST /api/v1/numbers/network-apis/device-status:reachability Surface the operator’s network-asserted reachability for a device without contacting it. NOT_CONNECTED is a corroborating fraud signal.

string

required

E.164 number of the device.

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

{ "data": { "reachabilityStatus": "CONNECTED_DATA" }, "meta": { "request_id": "req_naas_007" } }

reachabilityStatus is one of CONNECTED_DATA, CONNECTED_SMS, NOT_CONNECTED.

Carrier Billing

POST /api/v1/numbers/network-apis/carrier-billing:charge Charge a one-time payment to the end-user’s mobile-operator bill (Direct Carrier Billing). The per-transaction amount is capped server-side; a request above the cap is rejected with 422 before it reaches the operator.

string

required

E.164 number to bill.

number

required

Charge amount in major currency units (e.g. 1.99). Positive and finite.

string

required

ISO-4217 alphabetic currency code (e.g. EUR).

string

required

Human-readable description shown on the operator-bill line (max 140 chars).

string

Your own reconciliation reference, echoed to the operator.

string

Idempotency key so a retried charge is not double-billed.

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/carrier-billing:charge" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+14155550100",
    "amount": 1.99,
    "currency": "EUR",
    "description": "Premium feature unlock",
    "merchantReference": "order_000123",
    "idempotencyKey": "env_9f2e1c_order_000123"
  }'

{ "data": { "paymentId": "pay_abc123", "status": "captured" }, "meta": { "request_id": "req_naas_008" } }

Tenant-owned control: billing on the operator’s bill is a tenant-managed capability. Your tenant’s deployment configuration sets the per-transaction cap the server enforces; a charge above it is rejected with 422 before it ever reaches the operator.

Age Verification

POST /api/v1/numbers/network-apis/age-verification:verify Operator-asserted check that a subscriber is at least ageThreshold years old, for age-gated commerce. Returns a verdict only — never a date of birth — and fails closed (anything but an explicit affirmative reads as not old enough).

string

required

E.164 number of the subscriber.

integer

required

Minimum age to assert, in years (13–120).

string

Optional identity attribute that raises match confidence.

string

Optional given name.

string

Optional family name.

string

Optional date of birth.

string

Optional ID / document number.

string

Optional email.

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

{ "data": { "ageVerified": true, "ageThreshold": 18, "ageCheck": "true" }, "meta": { "request_id": "req_naas_009" } }

Scam Signal

POST /api/v1/numbers/network-apis/scam-signal:assess Real-time anti-APP-fraud network-signal dip for a number. Returns a normalised, fail-safe verdict — the three anonymised signals plus a coarse risk level — so a bank/fintech can make the final allow/review/block call at the moment of a live transaction. No call content is ever accessed.

string

E.164 number. Provide exactly one of phoneNumber or hashedPhoneNumber.

string

SHA-256 hash of the E.164 number.

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

{
  "data": {
    "scam_signal_detected": false,
    "risk_level": "low",
    "signals": { "active_call": false, "call_forwarding": false, "sim_swap": false }
  },
  "meta": { "request_id": "req_naas_010" }
}

Identity Risk Score

POST /api/v1/numbers/network-apis/risk:score Fuse the operator CAMARA signals (SIM swap, device status, device location, number verification, operator-asserted call forwarding) together with caller-held signals (roaming, reputation, call forwarding) into one weighted transaction-risk verdict with reason codes. Callable at login / signup / checkout / payout — not just on an OTP send. Each live signal is fetched fail-soft: an unconfigured or failing signal is reported unavailable and contributes nothing rather than failing the request. When a CAMARA operator is configured, risk:score automatically dips the same operator-asserted call-forwarding signal used by Scam Signal — the carrier itself confirming unconditional forwarding is active on the line, mirroring Twilio Lookup v2’s paid “Call Forwarding” data package. This carrier-grade signal is fused at a higher weight than the callForwardingUnconditional field below (a self-reported/derived value you already hold), and the two are independent: you don’t need an operator connection to pass your own signal in, and an operator dip never requires you to supply one.

string

required

E.164 number to score.

object

Optional business context (action, reference) echoed back, not scored.

object

Optional claimed geofence (latitude, longitude, radius, maxAge) that drives Device-Location Verification.

integer

default:"240"

SIM Swap look-back window in hours (1–2400).

string

Device-bound Silent-Auth token; when present, possession is checked.

string

Caller-held line reputation: low, medium, high, unknown.

boolean

Caller-held roaming state.

boolean

Caller-held unconditional call-forwarding state.

object

Per-request weight overrides (0–100 each).

object

Per-request decision-threshold overrides (review, deny).

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/risk:score" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+14155550100",
    "simSwapMaxAge": 720,
    "roaming": false,
    "reputationRiskLevel": "low",
    "callForwardingUnconditional": false,
    "context": { "action": "login", "reference": "sess_7f31c2" }
  }'

{
  "data": {
    "decision": "allow",
    "risk_score": 12,
    "risk_level": "low",
    "reasons": [],
    "signals_evaluated": ["simSwapped", "deviceReachable"],
    "signals_unavailable": ["deviceLocation"]
  },
  "meta": { "request_id": "req_naas_011" }
}

Tenant-owned control: default weights and thresholds are deployment-level tenant settings. The per-request weights / thresholds overrides let a tenant tune the verdict without touching the shared surface configuration.

Quality-on-Demand (QoD) sessions

Programmable QoS data bearers: request a low-latency / high-throughput data session for a device on demand, read its status, extend it, and tear it down. QoD shapes a data bearer only.

Create a session

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

string

required

E.164 number of the target device.

string

required

Application server IPv4 the optimized bearer targets.

string

Optional application server IPv6.

string

required

Operator QoS profile id (e.g. QOS_E low-latency, QOS_L throughput).

integer

default:"3600"

Requested session duration in seconds (1–86400).

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/network-apis/qod-sessions" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+14155550100",
    "applicationServerIpv4": "203.0.113.10",
    "qosProfile": "QOS_E",
    "duration": 3600
  }'

{ "data": { "sessionId": "qod_abc123", "qosStatus": "AVAILABLE", "expiresAt": "2026-06-28T13:00:00Z" }, "meta": { "request_id": "req_naas_012" } }

Get a session

GET /api/v1/numbers/network-apis/qod-sessions/{sessionId} Read the current status of a session.

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

{ "data": { "sessionId": "qod_abc123", "qosStatus": "AVAILABLE" }, "meta": { "request_id": "req_naas_012g" } }

Extend a session

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

integer

required

Additional seconds to add to the live session (1–86400).

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

{ "data": { "sessionId": "qod_abc123", "qosStatus": "AVAILABLE" }, "meta": { "request_id": "req_naas_012x" } }

Delete a session

DELETE /api/v1/numbers/network-apis/qod-sessions/{sessionId} Tear down a session. Returns 204 No Content.

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

Errors

503

No GSMA/CAMARA operator is configured for this deployment. The surface fails closed — call Operator status to check before integrating.

422

The request body failed validation, the operator could not process it (e.g. no subscriber for the number), or a Carrier-Billing amount exceeded the per-transaction cap.

502

The operator / aggregator returned an unexpected error. Phone numbers in error details are masked.

Network signals before you send — the task-level guide: gate an outbound campaign on SIM-swap + roaming, fuse risk:score into a login flow, replace an SMS OTP with Silent Auth, run KYC-match onboarding, check operator status before leaning on coverage, and when QoD matters.

API Reference

All Endpoints

Network APIs: GSMA Open Gateway and CAMARA endpoints

Network APIs

Using the SDKs

Operator status

Number Verification (Silent Auth)

SIM Swap

Check

Retrieve date

Subscriptions (continuous monitoring)

Device Swap

Device Roaming Status

KYC Match

Device Location Verification

Device Status reachability

Carrier Billing

Age Verification

Scam Signal

Identity Risk Score

Quality-on-Demand (QoD) sessions

Create a session

Get a session

Extend a session

Delete a session

Errors

​Network APIs

​Using the SDKs

​Operator status

​Number Verification (Silent Auth)

​SIM Swap

​Check

​Retrieve date

​Subscriptions (continuous monitoring)

​Device Swap

​Device Roaming Status

​KYC Match

​Device Location Verification

​Device Status reachability

​Carrier Billing

​Age Verification

​Scam Signal

​Identity Risk Score

​Quality-on-Demand (QoD) sessions

​Create a session

​Get a session

​Extend a session

​Delete a session

​Errors

​Related guides

Network APIs

Using the SDKs

Operator status

Number Verification (Silent Auth)

SIM Swap

Check

Retrieve date

Subscriptions (continuous monitoring)

Device Swap

Device Roaming Status

KYC Match

Device Location Verification

Device Status reachability

Carrier Billing

Age Verification

Scam Signal

Identity Risk Score

Quality-on-Demand (QoD) sessions

Create a session

Get a session

Extend a session

Delete a session

Errors

Related guides