API reference

The Verification API is a JSON REST API for starting, reporting, and checking phone number verifications. All endpoints use the /api/v1 base path and require an Authorization header. See Authentication.

Base URLs

Environment	Base URL
Production	https://verification.didww.com
Sandbox	https://verification-sandbox.didww.com

Note

Use the sandbox environment to test your integration without charging your account or contacting real destinations. Use credentials created in the same environment as the selected base URL. Sandbox and production credentials are not interchangeable. See Choose an environment.

Endpoints

Method	Path	Description
POST	/api/v1/verifications	Start a verification.
PATCH / PUT	/api/v1/verifications/{id}	Report the code the user submitted.
GET	/api/v1/verifications/{id}	Get the current status of a verification.
PATCH / PUT	/api/v1/verifications/by_number/{number}	Report the code for the latest verification associated with a phone number.
GET	/api/v1/verifications/by_number/{number}	Get the status of the latest verification for a phone number.

Request and response format

Send request bodies with Content-Type: application/json and request JSON responses with Accept: application/json.

Successful endpoint responses return the verification under a top-level data key. Unsuccessful HTTP responses return an errors array. See Errors and status codes.

OpenAPI specification

A machine-readable OpenAPI 3.0 description of the Verification API is available as a JSON file:

OpenAPI specification

Import it into Postman, Insomnia, or an OpenAPI code generator, or point an AI assistant at it. See AI best practices for guidance on using the specification with AI tools.

The verification object

The start, report, and status endpoints all return the same verification object under a top-level data key.

Field	Type	Availability	Description
id	string	Always	Verification identifier (UUID).
destination	string	Always	Destination number normalized to E.164 without a leading +.
delivery_method	string	Always	The method used to deliver the verification challenge. Supported values are sms and callout.
fee	string	Always	Quoted verification fee including VAT, represented as a decimal string, for example "0.06". The fee is charged only when the verification becomes verified. Delivery costs are billed separately.
status	string	Always	The current state of the verification. Supported values are pending, verified, failed, expired, and denied.
error_code	string	Always (nullable)	Machine-readable reason for a failed, expired, or denied verification. The value is null when status is pending or verified. See Errors.
error_detail	string	Always (nullable)	Fixed human-readable text for error_code. It is null whenever error_code is null. Display this text when needed, but use error_code in application logic.
expires_at	string	Always	When the verification expires, in ISO 8601 format.
sms	object	SMS only	Contains template, language, and interception_timeout. Includes app_hash only when it was accepted and stored for the verification. See SMS.
callout	object	Phone call only	Contains language. See Phone call.

Each response includes at most one delivery-specific object, named after delivery_method.

Both sms.language and callout.language report the language the API selected, which is not necessarily the first one requested. Compare the returned tag with the list you sent to detect a fallback to en-US.