Risk API

The Risk API fuses the anti-fraud detectors already running across your Orbit account into one composite verdict you can query before committing spend on an SMS send or a call. It answers a single question — “is this destination safe to reach right now?” — without you having to call each detector yourself and reconcile the scores.

Live SMS-pumping / artificial-traffic score — always computed from destination-prefix patterns, recent send velocity, delivery-conversion rate, and geo-spread.
URL/link-reputation score — computed automatically whenever you pass a message_body, by scanning every URL in it.
Verify Fraud Guard and Voice Biometrics scores — optional pass-through inputs from your own session-level checks, folded into the composite when supplied.

The endpoint is read-only and advisory: it sends nothing, routes nothing, and enforces nothing. The Devotel softswitch remains the sole outbound path for calls and SMS — Risk only tells you what it would recommend. Base path: /api/v1/risk Authentication: API key (X-API-Key) or session JWT. Rate limit: 120 requests/minute per tenant.

Method	Path	Purpose
`POST`	`/api/v1/risk/score`	Composite cross-channel Trust & Fraud score for a destination

When to call it

Call /api/v1/risk/score at the point you’d otherwise commit spend:

Before an outbound SMS/WhatsApp send to a destination you haven’t messaged before.
Before dialing a destination that has flagged in your delivery reports.
Alongside a Verify OTP send, passing along the Fraud Guard score you already computed for that session so it’s folded into one number.
Alongside a Voice Biometrics challenge, passing its score the same way.

The response is a recommendation, not an enforcement action — your application decides whether to allow, hold for review, or block, the same way you’d act on a credit-card AVS result. Risk never sends, routes, or blocks anything on its own; wiring the recommendation into your send flow (allow / hold / drop) is up to your integration.

Request body

Field	Type	Default	Notes
`destination`	string	—	Required. E.164 destination the score is requested for.
`channel`	string	`sms`	One of `sms`, `whatsapp`, `voice`, `verify`. Drives the SMS-pumping velocity aggregate.
`message_body`	string	—	Optional, ≤5000 chars. Every URL in it is reputation-scanned and folded into the composite.
`verify_signal`	object	—	Optional pass-through `{ score, reasons[] }` from your own Verify Fraud Guard evaluation for this recipient.
`voice_biometrics_signal`	object	—	Optional pass-through `{ score, reasons[] }` from your own Voice Biometrics challenge for this session.

score in either pass-through object is an integer 0-100; reasons is up to 20 short strings (≤200 chars each), echoed back inside the channel breakdown.

Scenario 1 — score-only lookup

The smallest useful call: a destination and a channel, nothing else. The SMS-pumping detector is the only signal present unless you supply more, so the composite equals that detector’s score.

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

import requests

resp = requests.post(
    "https://api.orbit.devotel.io/api/v1/risk/score",
    headers={"X-API-Key": "dv_live_sk_your_key_here"},
    json={"destination": "+14155552671", "channel": "sms"},
    timeout=10,
)
resp.raise_for_status()
print(resp.json()["data"]["band"])  # low | elevated | high | critical

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	body, _ := json.Marshal(map[string]string{
		"destination": "+14155552671",
		"channel":     "sms",
	})
	req, _ := http.NewRequest(
		"POST",
		"https://api.orbit.devotel.io/api/v1/risk/score",
		bytes.NewReader(body),
	)
	req.Header.Set("X-API-Key", "dv_live_sk_your_key_here")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var out struct {
		Data struct {
			Score          int    `json:"score"`
			Band           string `json:"band"`
			Recommendation string `json:"recommendation"`
		} `json:"data"`
	}
	json.NewDecoder(resp.Body).Decode(&out)
	fmt.Println(out.Data.Band) // low | elevated | high | critical
}

{
  "data": {
    "destination": "+14155552671",
    "channel": "sms",
    "score": 8,
    "band": "low",
    "recommendation": "allow",
    "channels": [
      { "channel": "sms_pumping", "present": true, "score": 8, "reasons": [] },
      { "channel": "url_reputation", "present": false, "score": 0, "reasons": [] },
      { "channel": "verify_fraud", "present": false, "score": 0, "reasons": [] },
      { "channel": "voice_biometrics", "present": false, "score": 0, "reasons": [] }
    ]
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-08-07T10:14:22Z"
  }
}

Walk the response field by field:

score — 0-100 composite, always the worst present channel score (never averaged down, so one bad signal can’t be diluted by clean ones). Here only sms_pumping was present, so the composite equals its 8.
band — coarse read of the score. The cutoffs are the same ones the SMS-pumping scorer uses, so a band means the same thing on this composite as it does on the single-channel signals:
Score Band Recommendation
0-24 low allow
25-49 elevated allow
50-79 high review
80-100 critical block
recommendation — advisory only: allow, review, or block. Only high and critical move it off allow.
channels — full transparency breakdown, always in the same four-entry order. A channel with present: false contributed a score of 0 — it never invents risk for a signal you didn’t supply.
meta.request_id — echo this in support tickets; it ties the verdict to the exact signals that produced it.

Score	Band	Recommendation
0-24	`low`	`allow`
25-49	`elevated`	`allow`
50-79	`high`	`review`
80-100	`critical`	`block`

Scenario 2 — pre-send guard with Verify and Voice signals

When you’ve already run a Verify Fraud Guard check or a Voice Biometrics challenge for this session, pass their scores through instead of reconciling four numbers yourself. The composite takes the worst present signal — supply a high Verify score and the recommendation flips.

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": "verify",
    "verify_signal": { "score": 62, "reasons": ["geo_mismatch", "sim_swap_recent"] },
    "voice_biometrics_signal": { "score": 12, "reasons": [] }
  }'

import requests

resp = requests.post(
    "https://api.orbit.devotel.io/api/v1/risk/score",
    headers={"X-API-Key": "dv_live_sk_your_key_here"},
    json={
        "destination": "+14155552671",
        "channel": "verify",
        # From the riskScore on your POST /verify/send response:
        "verify_signal": {"score": 62, "reasons": ["geo_mismatch", "sim_swap_recent"]},
        # From your /verify/voice-biometrics/* challenge result:
        "voice_biometrics_signal": {"score": 12, "reasons": []},
    },
    timeout=10,
)
resp.raise_for_status()
print(resp.json()["data"]["recommendation"])  # review

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	body, _ := json.Marshal(map[string]interface{}{
		"destination": "+14155552671",
		"channel":     "verify",
		"verify_signal": map[string]interface{}{
			"score":   62,
			"reasons": []string{"geo_mismatch", "sim_swap_recent"},
		},
		"voice_biometrics_signal": map[string]interface{}{
			"score":   12,
			"reasons": []string{},
		},
	})
	req, _ := http.NewRequest(
		"POST",
		"https://api.orbit.devotel.io/api/v1/risk/score",
		bytes.NewReader(body),
	)
	req.Header.Set("X-API-Key", "dv_live_sk_your_key_here")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var out struct {
		Data struct {
			Score          int    `json:"score"`
			Recommendation string `json:"recommendation"`
		} `json:"data"`
	}
	json.NewDecoder(resp.Body).Decode(&out)
	fmt.Println(out.Data.Recommendation) // review
}

The same destination, with and without the pass-through signals — the Verify Fraud Guard score (62) now drives the verdict from allow to review: Without pass-through signals (destination + channel only):

{
  "data": {
    "destination": "+14155552671",
    "channel": "verify",
    "score": 8,
    "band": "low",
    "recommendation": "allow",
    "channels": [
      { "channel": "sms_pumping", "present": true, "score": 8, "reasons": [] },
      { "channel": "url_reputation", "present": false, "score": 0, "reasons": [] },
      { "channel": "verify_fraud", "present": false, "score": 0, "reasons": [] },
      { "channel": "voice_biometrics", "present": false, "score": 0, "reasons": [] }
    ]
  },
  "meta": { "request_id": "req_def456", "timestamp": "2026-08-07T10:16:40Z" }
}

With verify_signal and voice_biometrics_signal supplied:

{
  "data": {
    "destination": "+14155552671",
    "channel": "verify",
    "score": 62,
    "band": "high",
    "recommendation": "review",
    "channels": [
      { "channel": "sms_pumping", "present": true, "score": 8, "reasons": [] },
      { "channel": "url_reputation", "present": false, "score": 0, "reasons": [] },
      { "channel": "verify_fraud", "present": true, "score": 62, "reasons": ["geo_mismatch", "sim_swap_recent"] },
      { "channel": "voice_biometrics", "present": true, "score": 12, "reasons": [] }
    ]
  },
  "meta": { "request_id": "req_ghi789", "timestamp": "2026-08-07T10:16:41Z" }
}

Two things to notice: the composite is max(channel scores), not an average — the low voice_biometrics 12 doesn’t pull the 62 down — and your reasons strings come back verbatim on the channel entry, so drill-down views can attribute the flip to Fraud Guard without a second call.

Scenario 3 — message-body URL scan

Pass message_body and every URL in it is reputation-scanned live — the body-level score is the worst-scoring URL, and that score enters the composite as a fourth channel. A body with two links scans both; the clean one can’t dilute the bad one.

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 delivery is held: verify customs at http://secure-royalmail.delivery-claim.top/confirm — or track at https://www.royalmail.com/track"
  }'

import requests

resp = requests.post(
    "https://api.orbit.devotel.io/api/v1/risk/score",
    headers={"X-API-Key": "dv_live_sk_your_key_here"},
    json={
        "destination": "+14155552671",
        "channel": "sms",
        "message_body": (
            "Your delivery is held: verify customs at "
            "http://secure-royalmail.delivery-claim.top/confirm "
            "— or track at https://www.royalmail.com/track"
        ),
    },
    timeout=10,
)
resp.raise_for_status()
url_channel = next(
    c for c in resp.json()["data"]["channels"]
    if c["channel"] == "url_reputation"
)
print(url_channel["score"])  # worst-URL score

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	body, _ := json.Marshal(map[string]string{
		"destination":  "+14155552671",
		"channel":      "sms",
		"message_body": "Your delivery is held: verify customs at http://secure-royalmail.delivery-claim.top/confirm — or track at https://www.royalmail.com/track",
	})
	req, _ := http.NewRequest(
		"POST",
		"https://api.orbit.devotel.io/api/v1/risk/score",
		bytes.NewReader(body),
	)
	req.Header.Set("X-API-Key", "dv_live_sk_your_key_here")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var out struct {
		Data struct {
			Channels []struct {
				Channel string `json:"channel"`
				Score   int    `json:"score"`
			} `json:"channels"`
		} `json:"data"`
	}
	json.NewDecoder(resp.Body).Decode(&out)
	for _, c := range out.Data.Channels {
		if c.Channel == "url_reputation" {
			fmt.Println(c.Score) // worst-URL score
		}
	}
}

{
  "data": {
    "destination": "+14155552671",
    "channel": "sms",
    "score": 85,
    "band": "critical",
    "recommendation": "block",
    "channels": [
      { "channel": "sms_pumping", "present": true, "score": 8, "reasons": [] },
      { "channel": "url_reputation", "present": true, "score": 85, "reasons": ["brand_impersonation", "abused_tld", "no_tls", "lure_keywords"] },
      { "channel": "verify_fraud", "present": false, "score": 0, "reasons": [] },
      { "channel": "voice_biometrics", "present": false, "score": 0, "reasons": [] }
    ]
  },
  "meta": { "request_id": "req_jkl012", "timestamp": "2026-08-07T10:19:03Z" }
}

The url_reputation entry carries the per-URL view: score is the worst URL’s score and reasons is that URL’s finding codes — here the scanner fired on a brand token (royalmail) that isn’t the URL’s actual registrable domain, a commonly-abused .top TLD, plain http://, and smishing lure keywords (verify, confirm, customs, delivery). At 85 the composite crosses the 80+ critical cutoff and the recommendation becomes block. The second, legitimate royalmail.com link scored clean — both URLs were scanned, and the worst one wins. Bodies cap at 25 distinct URLs per scan and every URL in the body counts; URL-scoring has weight against phishing/smishing patterns specifically, so run this check whenever your send template includes user-supplied links.

Acting on a `band: hold` or `block` recommendation

The verdict is yours to enforce — Risk returns a recommendation only. Treat recommendation: "block" (80+, or high if you prefer caution) as “hold this send / call for review” in your own send flow. Common follow-ups:

Hold and re-check later — SMS-pumping velocity spikes decay; re-query the same destination after a quieter window rather than dropping the recipient permanently.
Route through Frequency Caps — your tenant-owned per-recipient send caps keep review-queue destinations from receiving anything until you release them.
Add the destination to Message Suppression — your tenant-owned opt-out/block list, when a recipient should stop receiving traffic entirely.
Check Number Intelligence — per-number reputation/fraud lookups outside the send path, when you want more context than the composite gives.

API Reference

All Endpoints

Risk API: unified cross-channel Trust & Fraud score

Risk API

When to call it

Request body

Scenario 1 — score-only lookup

Scenario 2 — pre-send guard with Verify and Voice signals

Scenario 3 — message-body URL scan

Acting on a `band: hold` or `block` recommendation

See also

​Risk API

​When to call it

​Request body

​Scenario 1 — score-only lookup

​Scenario 2 — pre-send guard with Verify and Voice signals

​Scenario 3 — message-body URL scan

​Acting on a band: hold or block recommendation

​See also

Risk API

When to call it

Request body

Scenario 1 — score-only lookup

Scenario 2 — pre-send guard with Verify and Voice signals

Scenario 3 — message-body URL scan

Acting on a `band: hold` or `block` recommendation

See also