# 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](../authentication.html#otp-verification-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](../getting-started.html#otp-verification-environments).

## Endpoints

| Method | Path | Description |
| --- | --- | --- |
| `POST` | [/api/v1/verifications](start-verification.html#otp-verification-api-start) | Start a verification. |
| `PATCH` / `PUT` | [/api/v1/verifications/{id}](report-verification.html#otp-verification-api-report) | Report the code the user submitted. |
| `GET` | [/api/v1/verifications/{id}](get-verification-status.html#otp-verification-api-status) | Get the current status of a verification. |
| `PATCH` / `PUT` | [/api/v1/verifications/by\_number/{number}](report-verification-by-number.html#otp-verification-api-report-by-number) | Report the code for the latest verification associated with a phone number. |
| `GET` | [/api/v1/verifications/by\_number/{number}](get-verification-status-by-number.html#otp-verification-api-status-by-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](errors.html#otp-verification-api-errors).

## OpenAPI specification

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

[OpenAPI specification](../../openapi/verification_api.json)

Import it into Postman, Insomnia, or an OpenAPI code generator, or point an AI assistant at
it. See [AI best practices](../ai-best-practices.html#otp-verification-ai) 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](errors.html#otp-verification-api-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: the creation time plus the **Code timeout** of the OTP application (60 to 600 seconds, 300 by default). |
| `sms` | `object` | SMS only | Contains `template`, `language`, `interception_timeout`, and `code_length`. Includes `app_hash` only when it was accepted and stored for the verification. See [SMS](../verification-methods/sms.html#otp-verification-method-sms). |
| `callout` | `object` | Phone call only | Contains `language` and `code_length`. See [Phone call](../verification-methods/phone-call.html#otp-verification-method-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`.

On this page