Worked samples

Worked request and response samples

Copy a request body as written, substitute your own value, 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 when the caller authenticates with a dashboard session instead of a server-to-server key. The three end to end loops. Number Verification (Silent Auth) proves the SIM behind the asserted number is in the device that made the call, SIM Swap answers whether that SIM changed inside a look-back window, and Device Location answers whether the device is inside a claimed geofence without ever returning coordinates. Fails closed is the rule for each of them: anything that is not an explicit affirmative reads as a negative.

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());

{
  "data": {
    "devicePhoneNumberVerified": true
  },
  "meta": {
    "request_id": "req_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_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.

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_dlv_s3",
    "timestamp": "2026-09-09T12:00:02.000Z",
    "test_mode": true
  }
}

Error envelope — operator-side rejection

An off-spec body (a non-E.164 number, an out-of-range radius) 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 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 this shape 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_err_s4",
    "timestamp": "2026-09-09T12:00:03.000Z"
  }
}

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

API Reference

All Endpoints

Worked request and response samples

1. Number Verification (Silent Auth)

2. SIM Swap check

3. Device Location verification

Error envelope — operator-side rejection

​Worked request and response samples

​1. Number Verification (Silent Auth)

​2. SIM Swap check

​3. Device Location verification

​Error envelope — operator-side rejection

Worked request and response samples

1. Number Verification (Silent Auth)

2. SIM Swap check

3. Device Location verification

Error envelope — operator-side rejection