Risk API

Risk endpoints exposed by the Devotel CPaaS API Base path: /api/v1/risk/score Endpoint count: 1

title: “Decode the composite verdict” description: “How the fused SMS-pumping, URL-reputation, Verify fraud, and voice-biometrics signals resolve into one 0-100 score, a band, and an advisory action.”

Decode the composite verdict

Score a destination before you commit a send or a call. Fraud and trust-operations teams wire this endpoint into their pre-send gate; callers also run it ahead of a high-value voice dispatch. The endpoint is read-only and advisory — it sends nothing, routes nothing, and enforces nothing — so you decide how to act on the recommendation it returns. The composite score folds four detectors into one verdict. The live SMS-pumping / artificial-traffic check and (when you pass message_body) the outbound link-reputation scan run on the platform side; your own Verify Fraud Guard and Voice Biometrics scores pass in as verify_signal / voice_biometrics_signal and are folded into the same number. The composite is the worst present channel score, so a bad link or a flagged destination cannot be washed out by a clean aggregate. Band cutoffs reuse the SMS-pumping scorer’s thresholds, so a “high” verdict means the same thing whether the signal came from one channel or the fused whole.

Score a destination with a body scan

The Node SDK has no typed helper for this surface yet — the generic request() keeps auth, retries, and the { data, meta } envelope identical. Copy either form as written and substitute your own destination: Request

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/risk/score" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "destination": "+14155552671",
  "channel": "sms",
  "message_body": "Your pickup is ready — track it at https://acme.example/track",
  "verify_signal": {
    "score": 24,
    "reasons": [
      "sim_swap_recent"
    ]
  }
}'

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/risk/score', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "destination": "+14155552671",
  "channel": "sms",
  "message_body": "Your pickup is ready — track it at https://acme.example/track",
  "verify_signal": {
    "score": 24,
    "reasons": [
      "sim_swap_recent"
    ]
  }
}),
})
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/risk/score", headers=headers, json={
  "destination": "+14155552671",
  "channel": "sms",
  "message_body": "Your pickup is ready — track it at https://acme.example/track",
  "verify_signal": {
    "score": 24,
    "reasons": [
      "sim_swap_recent"
    ]
  }
})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/risk/score", bytes.NewBuffer([]byte(`{
  "destination": "+14155552671",
  "channel": "sms",
  "message_body": "Your pickup is ready — track it at https://acme.example/track",
  "verify_signal": {
    "score": 24,
    "reasons": [
      "sim_swap_recent"
    ]
  }
}`)))
	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/risk/score')
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",
  "message_body": "Your pickup is ready — track it at https://acme.example/track",
  "verify_signal": {
    "score": 24,
    "reasons": [
      "sim_swap_recent"
    ]
  }
}.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/risk/score');
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",
  "message_body": "Your pickup is ready — track it at https://acme.example/track",
  "verify_signal": {
    "score": 24,
    "reasons": [
      "sim_swap_recent"
    ]
  }
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "destination": "+14155552671",
    "channel": "sms",
    "score": 82,
    "band": "critical",
    "recommendation": "block",
    "channels": [
      {
        "channel": "sms_pumping",
        "score": 82,
        "present": true
      },
      {
        "channel": "url_reputation",
        "score": 34,
        "present": true
      },
      {
        "channel": "verify_fraud",
        "score": 24,
        "present": true
      }
    ]
  },
  "meta": {
    "request_id": "req_risk",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

Score bands decode as: 0–24 low, 25–49 elevated, 50–79 high, 80–100 critical. Bands map to actions as critical → block, high → review, and elevated | low → allow. No pass-through scores and no message_body returns a clean score: 0 / band: "low" — the empty ask never reads as a threat. The per-channel channels array tells you which detector drove the verdict, so the composite is never a black box.

Unified cross-channel Trust & Fraud risk score for a destination

POST /api/v1/risk/score

Fuses SMS-pumping risk, URL reputation, and (optionally) the caller’s own Verify Fraud Guard / Voice Biometrics scores into one composite risk verdict a tenant can query pre-send / pre-call.

string

Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the Idempotency-Replay: true response header.

string (enum: true|false)

Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/risk/score" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

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/risk/score', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
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/risk/score", headers=headers, json={})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/risk/score", bytes.NewBuffer([]byte(`{}`)))
	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/risk/score')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.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/risk/score');
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
{}
JSON);
echo curl_exec($ch);

{
  "data": {
    "destination": "+14155552671",
    "channel": "sms",
    "score": 82,
    "band": "critical",
    "recommendation": "block",
    "channels": [
      {
        "channel": "sms_pumping",
        "score": 82,
        "present": true
      },
      {
        "channel": "url_reputation",
        "score": 34,
        "present": true
      },
      {
        "channel": "verify_fraud",
        "score": 24,
        "present": true
      }
    ]
  },
  "meta": {
    "request_id": "req_risk",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

API Reference

All Endpoints

Risk API

Risk API

title: “Decode the composite verdict” description: “How the fused SMS-pumping, URL-reputation, Verify fraud, and voice-biometrics signals resolve into one 0-100 score, a band, and an advisory action.”

Decode the composite verdict

Score a destination with a body scan

Unified cross-channel Trust & Fraud risk score for a destination

​Risk API

​title: “Decode the composite verdict” description: “How the fused SMS-pumping, URL-reputation, Verify fraud, and voice-biometrics signals resolve into one 0-100 score, a band, and an advisory action.”

​Decode the composite verdict

​Score a destination with a body scan

​Unified cross-channel Trust & Fraud risk score for a destination

Risk API

title: “Decode the composite verdict” description: “How the fused SMS-pumping, URL-reputation, Verify fraud, and voice-biometrics signals resolve into one 0-100 score, a band, and an advisory action.”

Decode the composite verdict

Score a destination with a body scan

Unified cross-channel Trust & Fraud risk score for a destination