Worked request and response samples

Copy a request body as written, substitute your own ids, and compare the response envelope. Errors follow Devotel Orbit’s { error, meta } envelope, shown once below under Error envelope.

Send a verification code

POST /api/v1/verify/send

Pick the channel you deliver the code on, and hold onto the returned verification_id for the check call. Request

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/verify/send" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "destination": "+14155552671",
  "channel": "sms",
  "template_id": "tmpl_9e8d7c6b5a4f3021e5d6c7b8"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/verify/send', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "destination": "+14155552671",
  "channel": "sms",
  "template_id": "tmpl_9e8d7c6b5a4f3021e5d6c7b8"
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/verify/send", headers=headers, json={
  "destination": "+14155552671",
  "channel": "sms",
  "template_id": "tmpl_9e8d7c6b5a4f3021e5d6c7b8"
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/verify/send", bytes.NewBuffer([]byte(`{
  "destination": "+14155552671",
  "channel": "sms",
  "template_id": "tmpl_9e8d7c6b5a4f3021e5d6c7b8"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/verify/send')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "destination": "+14155552671",
  "channel": "sms",
  "template_id": "tmpl_9e8d7c6b5a4f3021e5d6c7b8"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/verify/send');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "destination": "+14155552671",
  "channel": "sms",
  "template_id": "tmpl_9e8d7c6b5a4f3021e5d6c7b8"
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "verification_id": "ver_3f6a81c2d4e5471a9b0c2d5e",
    "destination": "+14155552671",
    "channel": "sms",
    "expires_at": "2026-08-01T12:10:00.000Z"
  },
  "meta": {
    "request_id": "req_send",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

Check a code

POST /api/v1/verify/check

Send the verification_id from the send call and the code the user typed. Request

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/verify/check" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "verification_id": "ver_3f6a81c2d4e5471a9b0c2d5e",
  "code": "123456"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/verify/check', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "verification_id": "ver_3f6a81c2d4e5471a9b0c2d5e",
  "code": "123456"
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/verify/check", headers=headers, json={
  "verification_id": "ver_3f6a81c2d4e5471a9b0c2d5e",
  "code": "123456"
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/verify/check", bytes.NewBuffer([]byte(`{
  "verification_id": "ver_3f6a81c2d4e5471a9b0c2d5e",
  "code": "123456"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/verify/check')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "verification_id": "ver_3f6a81c2d4e5471a9b0c2d5e",
  "code": "123456"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/verify/check');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "verification_id": "ver_3f6a81c2d4e5471a9b0c2d5e",
  "code": "123456"
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "verification_id": "ver_3f6a81c2d4e5471a9b0c2d5e",
    "status": "verified"
  },
  "meta": {
    "request_id": "req_check",
    "timestamp": "2026-08-01T12:00:30.000Z"
  }
}

Error envelope

An expired or wrong code returns 422 with VALIDATION_ERROR; repeated wrong codes are rate-limited.

422

{
  "error": {
    "code": "INVALID_CODE",
    "status": 422,
    "message": "verification code does not match"
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

Gate a verification on identity signals

POST /api/v1/verify/fraud-gate

Decide whether to trust a number before sending the OTP. One call fuses the three carrier-asserted takeover signals — SIM-swap recency, port-event (number recycling), and silent network auth possession — into a single allow / review / deny decision. Request

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/verify/fraud-gate" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "phone_number": "+14155552671",
  "number_recycled": false,
  "roaming": false
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/verify/fraud-gate', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "phone_number": "+14155552671",
  "number_recycled": false,
  "roaming": false
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/verify/fraud-gate", headers=headers, json={
  "phone_number": "+14155552671",
  "number_recycled": false,
  "roaming": false
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/verify/fraud-gate", bytes.NewBuffer([]byte(`{
  "phone_number": "+14155552671",
  "number_recycled": false,
  "roaming": false
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/verify/fraud-gate')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "phone_number": "+14155552671",
  "number_recycled": false,
  "roaming": false
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/verify/fraud-gate');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "phone_number": "+14155552671",
  "number_recycled": false,
  "roaming": false
}
JSON);
echo curl_exec($ch);

Add a device-bound access_token (from the three-legged Silent Auth flow) to also check possession, and pass any backups you already hold — number_recycled, roaming, reputation_risk_level, call_forwarding_unconditional. Operator-asserted results always win over the backups you supply; when no carrier integration is configured, the gate still answers from your backups and lists the operator signals under signals_unavailable.

{
  "data": {
    "phone_number": "+1415****",
    "decision": "deny",
    "risk_score": 90,
    "risk_level": "critical",
    "reasons": ["sim_swap_recent", "number_verification_failed"],
    "signals_evaluated": ["numberVerified", "simSwapped", "numberRecycled"],
    "signals_unavailable": [],
    "headline_signals": {
      "resolved": ["simSwap", "portEvent", "numberVerification"],
      "unavailable": []
    }
  },
  "meta": {
    "request_id": "req_gate",
    "timestamp": "2026-08-28T12:00:00.000Z"
  }
}

The three headline signals are audited in headline_signals so you can tell “SIM-swap came back clean” apart from “SIM-swap was not evaluated”. A missing signal always contributes zero risk in either direction — you can tune the fusion per request with weights (0-100 per signal) and thresholds (the review / deny cut points on the 0-100 score). Nothing is ever sent to the subscriber by this call; it is a read-only network check.

API Reference

All Endpoints

Worked request and response samples