​

Verify

​

Formats and recipient requirements

​

Limits and validation windows

​

Rate-limit + fraud surface

• Rate limiting — per-recipient hourly cap (default 5/hour; tuned via a verify profile rateLimitPerHour, org-level verify_recipient_hourly_cap, or platform default). 429 VERIFY_RECIPIENT_RATE_LIMITED receipts are per-recipient, not per-batch.
• Velocity limits — the verify profile fraud.velocityPerHour / fraud.velocityPerDay (values 1–100 and 1–1000) and the composite-risk verifier (lib/verify-fraud-guard.ts) that scores SIM-swap, port-event, and CAMARA possession.
• Resend cooldown — VERIFY_RESEND_COOLDOWN runs as a SET NX guard (30s per recipient) before the hourly INCR, so a resend burst does not consume an hourly slot.
• VoIP line-type guard — a tenant opt-in verify_line_type_policy allows voip_sms / voip_voice to be off (default), warn, or block, so VoIP line-types are gated on SMS and voice only by tenant choice. The default is off.

​

Verify-specific fraud pre-flight

​

Webhook semantics

• verification.approved — a /check matched the code; fires exactly once per verification via the compare-and-set (CAS) transition gate
• verification.failed — max_attempts were exhausted or the verification moved to a terminal unsuccessful state
• verification.sent — the code was handed to the provider successfully

​

Channel capability at a glance

​

Delivery channels

​

Factor channels

​

Send a Verification Code

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

​

Response

{
  "data": {
    "verification_id": "vrf_3f1c0b2a8e4d4f7a9c2b1e6d5a4c3b2a",
    "status": "pending",
    "channel": "sms",
    "expires_at": "2026-03-08T00:10:00Z"
  }
}

​

Fallback chain + fallback config

curl -X POST https://api.orbit.devotel.io/api/v1/verify/send \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "channel": "sms",
    "channels": ["sms", "voice", "email"],
    "fallback_config": {
      "channel_timeout_seconds": 60,
      "max_attempts_per_channel": 1
    }
  }'

​

Bulk send body

{
  "recipients": ["+14155552671", "+442071234567"],
  "channel": "sms",
  "profile_id": "vp_1c2b3a4d5e6f7g8h"
}

{
  "data": {
    "results": [
      { "to": "+14155552671", "status": "pending", "verification_id": "vrf_3f1c0b2a8e4d4f7a9c2b1e6d5a4c3b2a" },
      { "to": "+442071234567", "status": "failed", "error": "VERIFY_RECIPIENT_RATE_LIMITED" }
    ],
    "sent_count": 1,
    "failed_count": 1
  }
}

​

Check a Verification Code

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

​

Response

{
  "data": {
    "verification_id": "vrf_3f1c0b2a8e4d4f7a9c2b1e6d5a4c3b2a",
    "status": "approved",
    "channel": "sms"
  }
}

​

MFA Factors

• TOTP and backup-code write operations (create, verify, delete, and recovery-code regeneration) require the verify:write scope. Dashboard (session) callers must also hold an owner, admin, or developer role.
• TOTP and backup-code list (read) endpoints, along with every Verify Push and Passkey endpoint, are gated by authentication and per-tenant rate limiting only. They do not require an additional verify:write or verify:read scope, so any authenticated key scoped to the tenant can call them — restrict which keys reach these flows accordingly.

​

TOTP (authenticator app)

​

Backup codes

​

Verify Push

​

Passkeys (WebAuthn / FIDO2)

​

Magic Link

​

Features

• Auto-generated codes — secure random codes (4–8 digits)
• Multi-channel delivery — SMS, WhatsApp, Voice, Email, Viber, Telegram, RCS, Flashcall, plus silent and sna for device-fraud-sterile checks
• Channel fallback — automatic retry on a different channel if the first times out or fails
• Rate limiting — built-in protection against brute-force attacks
• Expiration — configurable TTL via profiles (default 10 minutes / 600s, max 3600s)
• Attempt limits — configurable max verification attempts per code (1–10, default 3)
• Locale support — localized message templates in 25 languages
• Fraud detection — SIM-swap pre-flight, VoIP-type gating (tenant opt-in), velocity thresholds, composite risk, and offline fraud-score scoring

​

Configuration options (send body)

Code expiry is not a /send parameter. Direct sends expire after the default 600s (10 minutes). To change the TTL, set expirySeconds on a verify profile and pass its profile_id — there is no expiry field on the send body.

​

Webhook Events

A SIM-swap pre-flight block does not emit a webhook. When the pre-flight check rejects a send, /send returns a synchronous 403 SIM_SWAP_DETECTED with last_swap_date and block_window_hours in the response details. No verification row is created and no verification.failed event fires, so wire failure/step-up triggers to the 403 response rather than the webhook.

​

Next steps

• Verify profiles: fallback chains and advanced factors — configure an ordered SMS → WhatsApp → voice chain, code length/TTL, per-channel templates, and pair the profile with push, TOTP, passkey, or voice-biometrics factors.
• Verify integration without our SDK — the plain-HTTP send/check flow with the full error matrix and webhook walkthrough.
• Troubleshooting: verify OTP — resend cooldowns, recipient caps, VoIP gating, and failover behavior you hit in production.
• Verify API reference — every endpoint, including profile CRUD and the factor suites.
• Verify audit log approvals — OTP changes that require an operator action.