Verify any phone.
On any channel they answer.

# Didit Phone Verification — integrate in 5 minutes

You are integrating Didit's Phone Verification module into <my_stack>.
Follow these steps exactly. Every URL, header, and enum value below is
canonical — do not paraphrase or "improve" them.

## 1. Provision an account
- Sign up: https://business.didit.me (no credit card required).
- Or provision programmatically: POST https://apx.didit.me/auth/v2/programmatic/register/
  (returns an API key bound to the workspace + application).

## 2. Two integration paths — pick one

### Path A — Workflow Builder (hosted UI)
Best when you want Didit to handle phone collection, country prefix UX,
channel routing, OTP entry, resend buttons, mobile/desktop handoff, and
accessibility for you.

1. Create a workflow that contains the PHONE feature:
   POST https://verification.didit.me/v3/workflows/
   Authorization header:  x-api-key: <your-api-key>
   Body: workflow_label, features array with the single entry
         { feature: "PHONE" }   (UPPERCASE — strict enum)
   Optional config: preferred_channel ("SMS" | "WHATSAPP" | "TELEGRAM" |
   "RCS" | "VIBER" | "CALL"), code_validity_seconds, max_code_attempts
   (default 2), max_resend_requests_per_24h (default 2).

2. Create a verification session for an end user:
   POST https://verification.didit.me/v3/session/
   Body: workflow_id (from step 1), vendor_data (your own user id),
         optional contact_details.phone in E.164 format
         (e.g. "+14155552671") to pre-fill and lock the number.
   Response: session_url — redirect the user to it.

3. Listen for webhook callbacks (see "Webhooks" below).

### Path B — Standalone server-to-server API
Best when you already own the phone-entry UX (mobile SDK, native
onboarding app, reseller pipeline) and want Didit to handle OTP delivery
+ risk scoring only. Two endpoints, called in sequence:

Step 1 — Send the code:
POST https://verification.didit.me/v3/phone/send/
Content-Type: application/json
Body fields:
  - phone_number  (required, string, E.164 format e.g. "+14155552671")
  - channel       (optional — "SMS" | "WHATSAPP" | "TELEGRAM" | "RCS" |
                   "VIBER" | "CALL". Omit to let Didit pick the best
                   available channel for the destination country and
                   carrier — automatic fallback routing.)
  - vendor_data   (optional, your user id for cross-session linkage)

Step 2 — Check the code:
POST https://verification.didit.me/v3/phone/check/
Content-Type: application/json
Body fields:
  - phone_number  (required, same E.164 number)
  - code          (required, the OTP the user typed)
  - vendor_data   (optional, same user id used in Step 1)

Response: JSON report — status, verification_method (the channel that
actually delivered), carrier object, is_disposable, is_virtual, warnings
array.

## 3. Channel routing — how the automatic fallback works
When channel is omitted on /v3/phone/send/, Didit picks the cheapest
+ most-deliverable channel for the destination:
  - SMS where deliverable and lowest cost (most countries)
  - WhatsApp in BR / IN / MX and other WhatsApp-dense markets
  - Telegram / RCS / Viber where carrier-side SMS is blocked or premium
  - CALL (voice OTP) as last-resort fallback when text channels fail
Each retry attempt may switch channels — the final delivery channel is
returned as verification_method in the report.

## 4. Webhooks (Path A only — Path B returns synchronously)
- Register a webhook destination once via
  POST https://verification.didit.me/v3/webhook/destinations/
  Body: url, subscribed_events: ["session.verified", "session.review_started",
                                  "session.declined"]
- Response includes secret_shared_key — store it.
- Every webhook delivery carries an X-Signature-V2 header you MUST verify
  before trusting the payload.  HMAC-SHA256 verification MUST run against the raw body bytes (the raw payload as Didit sent it) BEFORE any JSON parsing — re-serialising the parsed body changes whitespace and key order, which invalidates the signature.Algorithm:
    1. sortKeys(payload) recursively
    2. shortenFloats (truncate trailing zeros after the decimal point)
    3. JSON.stringify the result
    4. HMAC-SHA256 with the secret_shared_key
    5. Hex-encode, compare to the X-Signature-V2 header.

## 5. Reading the report (both paths return the same phone object)
- status: "Approved" | "Declined" | "In Review" | "Not Finished"
- phone_number_prefix: country prefix in international format ("+34")
- phone_number: subscriber number without the prefix
- full_number: full E.164 string ("+34600600600")
- country_code: ISO 3166-1 alpha-2 ("ES")
- country_name: full country name
- carrier: { name, type: "mobile" | "landline" | "voip" | "unknown" }
- is_disposable: boolean — temporary or throwaway number
- is_virtual: boolean — VoIP or virtual provider
- verification_method: the channel that actually delivered the code
  ("sms" | "whatsapp" | "viber" | "telegram" | "call")
- verification_attempts: number of code-entry tries
- verified_at: ISO 8601 timestamp
- warnings: Array<{ risk, log_type, short_description, long_description }>

Auto-decline risks (always enforced by Didit, not configurable):
- VERIFICATION_CODE_ATTEMPTS_EXCEEDED
- HIGH_RISK_PHONE_NUMBER
- PHONE_NUMBER_IN_BLOCKLIST

Configurable risks (action per workflow — Decline, Review, or Approve):
- DISPOSABLE_NUMBER_DETECTED
- VOIP_NUMBER_DETECTED
- DUPLICATED_PHONE_NUMBER

## 6. Attempt limits (defaults — overridable per workflow)
- Max code-entry attempts: 2 per session
- Max resend requests: 2 per phone number per 24 hours
- Code validity: 5 minutes from send
Hitting either limit fires VERIFICATION_CODE_ATTEMPTS_EXCEEDED and
auto-declines the session.

## 7. Hard rules — do not change
- Base URL for /v3/* endpoints is verification.didit.me (NOT apx.didit.me).
- Feature enum is UPPERCASE: PHONE, ID_VERIFICATION, LIVENESS, FACE_MATCH,
  AML, IP_ANALYSIS.
- Channel enum is UPPERCASE on input ("SMS", "WHATSAPP", "TELEGRAM",
  "RCS", "VIBER", "CALL") and lowercase on output ("sms", "whatsapp",
  "telegram", "rcs", "viber", "call").
- All phone numbers go in and come out as E.164 strings — including
  the leading "+" and country prefix.
- Auth header is x-api-key (lowercase, hyphenated).
- Webhook signature header is X-Signature-V2 (NOT X-Signature).
- Always verify webhook signatures before trusting payload data.
- Status casing matches exactly: "Approved", "Declined", "In Review",
  "Not Finished" (title-cased, space-separated).

## 8. Pricing reference (public)
- Didit fee: $0.03 per verification (the cheapest channel; some
  channels and countries cost more — see didit.me/pricing for the
  per-country, per-channel table).
- Carrier fee: variable by country and channel, billed as a
  pass-through with no Didit markup.
- 500 free checks every month, forever, on every account.
- You only pay when a message is SENT. If the user abandons before
  delivery, you are not charged.

## 9. Verify your integration
- Sandbox starts on signup at https://business.didit.me — no separate flag.
- Sandbox numbers: deterministic E.164 numbers return Approved by default;
  trigger Declined with the canonical "high-risk" sandbox number.
- Switch to live: flip the application's environment toggle in console.

When in doubt: https://docs.didit.me/core-technology/phone-verification/overview