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

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.

phoneNumber

string

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

hashedPhoneNumber

string

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

accessToken

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

{ "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.

phoneNumber

string

required

E.164 number to check.

maxAge

integer

default:"240"

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

{ "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.

phoneNumber

string

required

E.164 number to look up.

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

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.

phoneNumber

string

required

E.164 number whose KYC record to match against.

name

string

Full name to match.

givenName

string

Given (first) name.

familyName

string

Family (last) name.

birthdate

string

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

idDocument

string

National ID / document number.

string

Email address to match.

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

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.

phoneNumber

string

required

E.164 number of the device.

latitude

number

required

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

longitude

number

required

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

radius

integer

required

Geofence radius in metres (2000–200000).

maxAge

integer

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

{ "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.

phoneNumber

string

required

E.164 number of the device.

{ "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.

phoneNumber

string

required

E.164 number to bill.

amount

number

required

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

currency

string

required

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

description

string

required

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

merchantReference

string

Your own reconciliation reference, echoed to the operator.

idempotencyKey

string

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

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

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

phoneNumber

string

required

E.164 number of the subscriber.

ageThreshold

integer

required

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

name

string

Optional identity attribute that raises match confidence.

givenName

string

Optional given name.

familyName

string

Optional family name.

birthdate

string

Optional date of birth.

idDocument

string

Optional ID / document number.

string

Optional email.

{ "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.

phoneNumber

string

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

hashedPhoneNumber

string

SHA-256 hash of the E.164 number.

{
  "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) 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.

phoneNumber

string

required

E.164 number to score.

context

object

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

claimedLocation

object

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

simSwapMaxAge

integer

default:"240"

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

accessToken

string

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

reputationRiskLevel

string

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

roaming

boolean

Caller-held roaming state.

callForwardingUnconditional

boolean

Caller-held unconditional call-forwarding state.

weights

object

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

thresholds

object

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

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

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

phoneNumber

string

required

E.164 number of the target device.

applicationServerIpv4

string

required

Application server IPv4 the optimized bearer targets.

applicationServerIpv6

string

Optional application server IPv6.

qosProfile

string

required

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

duration

integer

default:"3600"

Requested session duration in seconds (1–86400).

{ "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.

Extend a session

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

requestedAdditionalDuration

integer

required

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

Delete a session

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

Errors

SERVICE_UNAVAILABLE

503

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

VALIDATION_ERROR

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.

UPSTREAM_ERROR

502

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

API Reference

All Endpoints

Network APIs

Network APIs

Operator status

Number Verification (Silent Auth)

SIM Swap

Check

Retrieve date

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

​Operator status

​Number Verification (Silent Auth)

​SIM Swap

​Check

​Retrieve date

​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

Operator status

Number Verification (Silent Auth)

SIM Swap

Check

Retrieve date

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