Overview#

OTP Verification confirms that a user actually controls a phone number. DIDWW delivers a one-time code by SMS or voice. Your application confirms the user by reporting the code.

The service combines a hosted REST API with client SDKs, so you can drive verifications from your backend, your mobile app, or both. Use it wherever a real, reachable phone number matters: securing sign-ups and logins, adding a second factor to sensitive actions, confirming a number before you provision a service, or reducing fraud and fake accounts.

What OTP verification does#

OTP Verification manages the verification attempt from start to finish. After you create an OTP application and authenticate your request, your application starts a verification for a destination number and chooses a supported delivery method. DIDWW delivers the challenge, tracks the attempt, and lets your application report the result or retrieve the latest status.

A verification has three main parts:

Destination: the phone number you want to verify.
Delivery method: the channel used to send the challenge.
Report: the code that your application sends back to confirm the user.

The API keeps the verification state, returns the current status, and provides machine-readable error information when the verification cannot be completed.

Supported verification methods#

Every verification delivers a challenge over one channel, chosen per request with the delivery_method field. SMS and phone call both deliver a numeric code for the user to report.

Method	API value	User reports	How the user is challenged
SMS	`sms`	`code`	A text message carrying the one-time code is sent to the number. The most familiar channel for end users.
Phone Call	`callout`	`code`	A call is placed and reads the one-time code aloud. Useful where SMS is unreliable or for landline numbers.

Note

Supported mobile SDKs can streamline these flows on the device, for example by automatically capturing SMS codes where supported. Over the REST API, your application collects the code from the user and reports it.

How a verification works#

Every verification follows the same three-step lifecycle regardless of delivery method:

        %%{init: {
  "theme": "base",
  "themeVariables": {
    "actorBkg": "#e0f2fe",
    "actorBorder": "#38bdf8",
    "actorTextColor": "#1f2d3d",
    "signalColor": "#1f2d3d",
    "signalTextColor": "#1f2d3d",
    "activationBkgColor": "#fef3c7",
    "activationBorderColor": "#facc15",
    "labelBoxBkgColor": "#ccfbf1",
    "labelBoxBorderColor": "#2dd4bf",
    "labelTextColor": "#1f2d3d"
  }
}}%%

sequenceDiagram
    participant App as Your application
    participant API as Verification API
    participant User as End user

    App->>API: POST /api/v1/verifications (start)
    API->>User: Deliver code / place call
    API-->>App: 201 Created - verification id, status: pending
    User->>App: Enters code
    App->>API: PATCH /api/v1/verifications/{id} (report)
    API-->>App: 200 OK - status: verified / failed
    App->>API: GET /api/v1/verifications/{id} (status, optional)
    API-->>App: 200 OK - current status

Start: call POST /api/v1/verifications with the destination number and delivery method. DIDWW routes the request, delivers the challenge, and returns a verification id with status pending.
Report: when the user submits the code, call PATCH /api/v1/verifications/{id} with the code. The response carries the resulting status.
Status: at any time, call GET /api/v1/verifications/{id} to read the current status.

Each verification is short-lived: it expires two minutes after it is created, and the value may be reported at most three times before the verification fails.

Using the SDKs and the REST API#

You can integrate at whichever layer fits your architecture:

Backend, server-to-server: start and report verifications directly from your server with the REST API or a server SDK, keeping your application secret private. This is the simplest setup.
Untrusted clients with a gate: when a verification originates from a device or browser that only holds a public key, add a request callback. DIDWW calls your backend before delivering anything, and your server approves or rejects the attempt in real time.

Whichever layer you choose, authenticate with the right auth mode for the trust level of the caller, and consider a request callback to keep control on your own server.

Verification status#

The status field on a verification is one of:

Status	Meaning
`pending`	The verification has been started and is awaiting the user’s report.
`verified`	The reported code matched, and the number is confirmed.
`failed`	The verification could not be completed because of a wrong code, too many attempts, delivery failure, or expiry before a correct report.
`expired`	The verification lifetime elapsed without a successful report.
`denied`	The verification was rejected before delivery, typically by your request callback.

When a verification is not successful, the error_code field carries a machine-readable explanation and error_detail carries the matching human-readable text. See Errors and Status Codes for the full list of error codes and HTTP status codes.

Next steps#

Start with Getting Started to create an OTP application and prepare your credentials. Then review Authentication, choose the Verification Methods that fit your product flow, or pick an SDK for your language.

If you use AI coding tools to build an integration, see AI Best Practices.