Composite trust & fraud risk check before a send

Orbit ships four independent fraud detectors, each answering its own slice of “is this destination about to cost me money”: SMS-pumping (artificial traffic) scoring, outbound URL reputation, Verify Fraud Guard on the OTP path, and Voice Biometrics anti-spoofing. Until now you had to query each one separately and reconcile four differently-banded numbers by hand. POST /api/v1/risk/score fuses them into one 0–100 composite verdict you can query before committing an SMS send, a campaign launch, or a call. Everything on this page is advisory and read-only. Scoring never sends, routes, blocks, or modifies an outbound message — the Devotel softswitch remains the sole outbound path for every channel. The platform computes the verdict; the decision to act on it is yours.

1. Four siloed detectors, one composite

Each detector grew up behind its own surface with its own request and response shape:

Detector	Its own surface	What it scores
SMS-pumping / AIT	`POST /messages/risk-signals`	Destination-prefix patterns, send velocity, delivery conversion, 24h geo-spread, outbound blocklist hits
URL reputation	used inline by the compose-time linter	Every link in an outbound body, flagged on phishing / malware / shortened-URL findings
Verify Fraud Guard	applied on `POST /verify/send` under a configured policy	SIM-swap, geo, and number-intelligence signals on the OTP send path
Voice Biometrics	returned inside an enroll/verify challenge	Spoof / deepfake probability on a captured audio sample

The composite exists so a single pre-send check can see the whole picture. Two of the four components are always computed live for you — the SMS-pumping score and (when you supply a message body) the URL-reputation scan — because both are free, local lookups with no paid upstream call. The other two are accepted as pass-through scores (next section), because triggering them on your behalf would spend money or demand input you have not provided.

2. Request shape

curl -X POST "https://api.orbit.devotel.io/api/v1/risk/score" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "+14155552671",
    "channel": "sms",
    "message_body": "Your order shipped — track it at https://acme.example/t/98421",
    "verify_signal": { "score": 12, "reasons": ["low_sim_swap_risk"] },
    "voice_biometrics_signal": { "score": 4, "reasons": [] }
  }'

Field	Required	Meaning
`destination`	yes	E.164 destination you are about to send to or call.
`channel`	no (default `sms`)	One of `sms`, `whatsapp`, `voice`, `verify`. Drives which velocity aggregate the SMS-pumping leg reads.
`message_body`	no	The outbound body. When supplied, every URL in it is reputation-scanned and folded into the composite. Omit it and the URL leg simply reports `present: false`.
`verify_signal`	no	A `{ score, reasons }` pair (score 0–100) you already hold from a Verify Fraud Guard evaluation for this recipient this session — for example the `riskScore` on a recent `POST /verify/send` response.
`voice_biometrics_signal`	no	A `{ score, reasons }` pair (score 0–100) you already hold from a Voice Biometrics challenge for this session.

Why the two pass-through fields exist instead of the endpoint querying those detectors itself: a Verify Fraud Guard evaluation spends a paid number-intelligence lookup, and a Voice Biometrics score requires a captured audio sample. Neither may be triggered silently on your behalf from a scoring endpoint. If you already ran either check this session, fold its score in here and get one composite decision; if you have not run one, omit the field — a missing channel contributes nothing rather than inventing risk. The endpoint authenticates with the messages:read or messages:write scope and is rate-limited to 120 requests per minute per tenant. A malformed body returns a 422 naming the offending field.

3. Interpreting the composite

Every response returns the same three top-level fields, plus a per-channel breakdown:

score — the composite risk score, 0 (clean) to 100 (certain block). It is the maximum of the present channels — the worst signal wins. A message flagged on any single channel surfaces instead of being averaged back to low, and a destination with no signal at all returns a clean 0 rather than a misleading average.
band — the score bucketed: below 25 low, 25–49 elevated, 50–79 high, 80+ critical. These are the same cut-offs the standalone SMS-pumping scorer uses, so a band means the same thing on POST /messages/risk-signals and here.
recommendation — the mapped advisory action: allow for low / elevated, review for high, block for critical.
channels — one entry per detector (sms_pumping, url_reputation, verify_fraud, voice_biometrics) with present, that channel’s own score, and its machine-readable reasons. The composite is never a black box: the entry driving it is the one with present: true and the highest score.

A flagged response looks like:

{
  "data": {
    "destination": "+14155552671",
    "channel": "sms",
    "score": 85,
    "band": "critical",
    "recommendation": "block",
    "channels": [
      { "channel": "sms_pumping", "present": true, "score": 85, "reasons": ["high_risk_prefix"] },
      { "channel": "url_reputation", "present": true, "score": 0, "reasons": [] },
      { "channel": "verify_fraud", "present": true, "score": 12, "reasons": ["low_sim_swap_risk"] },
      { "channel": "voice_biometrics", "present": false, "score": 0, "reasons": [] }
    ]
  },
  "meta": { "request_id": "req_9f4c2e" }
}

Here the SMS-pumping leg drove the verdict; the Verify pass-through scored clean; Voice Biometrics was never supplied, so it reports present: false and contributes nothing.

4. Gate pattern — score the audience before a campaign dry-run

Use the composite before a launch, not after a bill. The natural gate combines two read-only calls: the launch dry-run tells you the audience and cost picture; the composite tells you whether the destinations in that audience are worth sending to. Worked pre-launch gate:

Dry-run the campaign — POST /api/v1/campaigns/{id}/dry-run returns the resolved audience size, the deliverable / suppressed / opted-out breakdown, projected cost against the wallet, and a ready_to_launch verdict. It never mutates state and never touches the wallet.
Score a sample of the audience — call POST /risk/score for each sampled destination with the campaign’s channel and message body.
Decide — launch only if the dry-run reports ready_to_launch: true and no sampled destination lands in your block threshold.

Node.js — pre-launch gate

const dryRun = await orbit.request('POST', `/api/v1/campaigns/${campaignId}/dry-run`, {});

if (!dryRun.data.ready_to_launch) {
  throw new Error('Dry-run not clean — fix audience or cost issues first');
}

for (const destination of sampledDestinations) {
  const verdict = await orbit.request('POST', '/api/v1/risk/score', {
    destination,
    channel: 'sms',
    messageBody: campaignBody,
  });
  if (verdict.data.recommendation === 'block') {
    throw new Error(`${destination} scores ${verdict.data.score} — suppress before launch`);
  }
}

// both gates passed — safe to launch

The same shape applies to a single high-cost send: score first, branch on recommendation, and only then dispatch. allow — proceed; review — queue for a human when the send is high-value; block — suppress the destination and log the decision. Enforcement always stays in your code; the endpoint only advises.

5. Channel examples

The channel value selects which velocity aggregate the SMS-pumping leg reads — set it to the channel you are actually about to use. SMS (the default):

curl -X POST "https://api.orbit.devotel.io/api/v1/risk/score" \
  -H "X-API-Key: $ORBIT_API_KEY" -H "Content-Type: application/json" \
  -d '{"destination": "+14155552671", "channel": "sms",
       "message_body": "Your code is 384216. Reply STOP to opt out."}'

WhatsApp — velocity reads the WhatsApp lane instead of the SMS lane:

{ "destination": "+14155552671", "channel": "whatsapp" }

Voice — score the outbound call target before a dialer or agent call; fold in a Voice Biometrics challenge score if you ran one this session:

{
  "destination": "+14155552671",
  "channel": "voice",
  "voice_biometrics_signal": { "score": 71, "reasons": ["spoof_suspected"] }
}

Verify — score the OTP destination and pass through the Fraud Guard evaluation you already received on a recent POST /verify/send:

{
  "destination": "+14155552671",
  "channel": "verify",
  "verify_signal": { "score": 88, "reasons": ["sim_swap_recent"] }
}

6. Limits and caveats

Read-only and advisory. The endpoint never dispatches, routes, or blocks anything. Outbound SMS and voice exit only through the Devotel softswitch; a block recommendation suppresses nothing until your own send code acts on it.
Tenant-owned decision. Thresholds, sampling, and what review means operationally are your configuration. If you want the platform to enforce a terminal allow / review / block decision, configure Fraud Shield on the messaging side or Fraud Guard on the Verify side — those are separate tenant-owned controls; this endpoint only scores.
No pass-through re-querying. verify_signal and voice_biometrics_signal are never re-evaluated server-side — supply scores you already hold from this session, or omit them.
Absent channel, no invented risk. A channel you did not supply (or a message body you did not send) reports present: false and counts as zero. An all-absent input returns score: 0, band: "low", not an error.
Score scope. The composite reflects the detectors listed above. A clean verdict is not a deliverability guarantee — it says nothing flagged on the fraud axes the platform measures.

Canonical pages: Risk API, SMS-pumping protection, Fraud Shield configuration, Voice biometrics enrollment, API recipes.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Composite trust & fraud risk check before a send

Composite trust & fraud risk check before a send

1. Four siloed detectors, one composite

2. Request shape

3. Interpreting the composite

4. Gate pattern — score the audience before a campaign dry-run

5. Channel examples

6. Limits and caveats

​Composite trust & fraud risk check before a send

​1. Four siloed detectors, one composite

​2. Request shape

​3. Interpreting the composite

​4. Gate pattern — score the audience before a campaign dry-run

​5. Channel examples

​6. Limits and caveats

Composite trust & fraud risk check before a send

1. Four siloed detectors, one composite

2. Request shape

3. Interpreting the composite

4. Gate pattern — score the audience before a campaign dry-run

5. Channel examples

6. Limits and caveats