Testing in sandbox#

Use the sandbox test numbers to simulate verification codes and predefined outcomes without sending an SMS message or placing a call to a real phone. You can test your verification flow and error handling, including automated tests, without a phone.

Note

Use the sandbox base URL https://verification-sandbox.didww.com with credentials from a sandbox OTP application. See Choose an environment.

Sandbox accounts#

Your sandbox account is approved automatically after you complete your account details and billing address in the DIDWW Sandbox User Panel.
Your sandbox account includes USD 1,000 in virtual credit for testing.
The verification fee is 0.
The sandbox never sends an SMS message or places a call to a real phone.

Verification responses depend on the number and selected delivery method:

Condition	API response
Number outside the test ranges	The start request returns `201 Created`, then the verification ends with `status` set to `failed` and `error_code` set to `dispatch_failed`.
Destination not supported by the selected delivery method	The start request returns `201 Created` with `status` immediately set to `failed` and `error_code` set to `destination_not_supported_for_channel`.

Test numbers#

Each scenario has ten US numbers and ten UK numbers. Replace X with any digit from 0 to 9 to select a number.

Use a different number in each parallel test. After a verification is approved for delivery, an OTP application must wait 30 seconds before starting another verification for the same number, regardless of the delivery method. The expired test scenario also starts this cooldown. See Repeated starts.

Per-second rate limits and the application’s daily and monthly volume limits also apply. See Limits.

Test numbers support both sms and callout. Before testing, check the application’s authentication mode and callback settings:

With public authentication, a callback URL must be configured. Without one, every test number except +1201555015X and +44207946015X returns status set to denied and error_code set to denied_missing_callback_url.
For scenarios that send a request callback, requests using public or basic authentication call the configured callback URL. To approve a verification, return { "action": "allow" } from your callback endpoint. Requests using application authentication skip the callback.
The slow-start and denied-by-callback scenarios simulate the callback outcome without contacting your callback endpoint. With public authentication, a callback URL must still be configured for these scenarios.

US number	UK number	Result
`+1201555010X`	`+44207946010X`	The sandbox simulates successful delivery and returns `status` set to `pending`. Reporting the test code changes `status` to `verified`.
`+1201555011X`	`+44207946011X`	The sandbox simulates successful delivery and returns `status` set to `pending`. Reporting the zero code changes `status` to `verified`.
`+1201555012X`	`+44207946012X`	The start request takes about 10 seconds to return, simulating a slow request callback. The verification has `status` set to `pending` and uses the test code. No request callback is sent. Use this scenario to test client timeouts and loading states.
`+1201555013X`	`+44207946013X`	The verification is created with `status` and `error_code` both set to `expired`. Reporting a code leaves the verification’s `status` set to `expired`.
`+1201555014X`	`+44207946014X`	The start request returns `201 Created`, then the verification ends with `status` set to `failed` and `error_code` set to `dispatch_failed`.
`+1201555015X`	`+44207946015X`	The start request returns `402 Payment Required` with the `balance_insufficient` error code.
`+1201555016X`	`+44207946016X`	The start request returns `201 Created` with `status` set to `failed` and `error_code` set to `destination_not_supported_for_channel`. Nothing is sent.
`+1201555017X`	`+44207946017X`	The start request returns `201 Created` with `status` set to `denied` and `error_code` set to `denied_by_callback`, simulating a callback that denies the verification. No request callback is sent, so no callback server is needed.

The UK test numbers use the London landline format and may be rejected by forms that accept only mobile numbers.

Test verifications appear in the OTP Verification logs and statistics of the DIDWW Sandbox User Panel. Try it out also accepts test numbers.

Codes for test numbers#

After starting a verification with a test number that simulates successful delivery or a slow start, you still need to report a code to complete it. The sandbox does not send an SMS message or place a call, so use the predefined code for that test scenario.

For example, with the default Code length of 6:

Start a verification for +12015550100, then report 123456 to change its status from pending to verified.
Start a verification for +12015550110, then report 000000 to get the same result.

The other test numbers in the same ranges use the same codes. The slow-start scenario uses the code shown for +12015550100. These rules also apply to the corresponding UK numbers.

If you change Code length in the OTP application, the code you must report changes too:

Code length	Code for `+12015550100`	Code for `+12015550110`
4	`1234`	`0000`
5	`12345`	`00000`
6 (default)	`123456`	`000000`
7	`1234567`	`0000000`
8	`12345678`	`00000000`

These codes apply to both sms and callout. You can check the code length in the start response’s sms.code_length or callout.code_length field.

Example#

The following example uses HTTP Basic authentication. Set OTP_APPLICATION_KEY and OTP_APPLICATION_SECRET to the key and secret of your sandbox OTP application. Its minimum authentication mode must allow basic requests. If a callback URL is configured, its endpoint must return { "action": "allow" } for this test to proceed.

The example assumes that Code length is 6. If your application uses a different length, use the code listed in Codes for test numbers.

Start an SMS verification for a test number:

curl https://verification-sandbox.didww.com/api/v1/verifications \
  -u "$OTP_APPLICATION_KEY:$OTP_APPLICATION_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{ "data": { "destination": "+12015550100", "delivery_method": "sms" } }'

Set VERIFICATION_ID to the data.id value from the response, then report the fixed code:

curl -X PATCH "https://verification-sandbox.didww.com/api/v1/verifications/$VERIFICATION_ID" \
  -u "$OTP_APPLICATION_KEY:$OTP_APPLICATION_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{ "data": { "delivery_method": "sms", "code": "123456" } }'

The response has data.status set to verified.

Reproduce other outcomes#

The following tests reproduce verification outcomes and request errors that can also occur in production. Unless a row says otherwise, use a test number that simulates successful delivery (+1201555010X or +44207946010X). Start a fresh verification for each report test.

Run each scenario separately and restore any changed settings before starting the next one. For scenarios that test your callback endpoint, use public or basic authentication with a configured callback URL. Requests using application authentication skip the callback. See Callbacks.

Outcome	How to trigger it	Result
Wrong code	For a pending verification, report a non-empty code that does not match the fixed code, such as `000000` when the fixed code is `123456`.	`422 Unprocessable Content` with the `code_invalid` error code. The verification’s `status` stays `pending`.
Too many attempts	For a new pending verification, report a non-empty incorrect code three times, then report a non-empty code once more.	The first three reports return `422 Unprocessable Content` with `code_invalid`. The fourth returns `200 OK` with `status` set to `failed` and `error_code` set to `too_many_attempts`, even if the submitted code is correct.
Superseded	Start a verification and leave it pending. After 30 seconds, but before it expires, start another verification for the same number in the same OTP application. Retrieve the first verification using its `id`.	The first verification has `status` set to `failed` and `error_code` set to `superseded`.
Cooldown	Start a verification approved for delivery, then request another verification for the same number in the same OTP application within 30 seconds.	The second request returns `429 Too Many Requests` with the `destination_in_cooldown` error code and a `Retry-After` header.
Volume limit	Use an OTP application with no volume usage for the current UTC day and an available monthly allowance. Set its Daily limit to `1` (see Set volume limits), then start verifications for two different test numbers that simulate successful delivery.	The first approved request uses the daily allowance. The second request returns `429 Too Many Requests` with the `volume_limit_reached` error code and a `Retry-After` header.
Country disabled	Add the United States to the country blocklist, then start a verification for `+12015550100`.	`201 Created` with `status` set to `denied` and `error_code` set to `destination_country_disabled`. The UK numbers keep working. The expired, balance-insufficient, and unsupported test numbers keep their own outcomes.
Application paused	Pause the OTP application, then start a verification for a test number that simulates successful delivery.	`201 Created` with `status` set to `denied` and `error_code` set to `application_paused`.
Invalid number	Start a verification for a malformed number, such as `+1201`.	`422 Unprocessable Content` with the `destination_invalid` error code.
Denied by your callback	Have your request callback return `{ "action": "deny" }`, then start a verification. To simulate this outcome without a callback server, use `+12015550170`.	`201 Created` with `status` set to `denied` and `error_code` set to `denied_by_callback`.
Invalid callback response	Have your request callback return a non-`2xx` status, invalid JSON, or an unsupported `action`, then start a verification.	`201 Created` with `status` set to `denied` and `error_code` set to `denied_invalid_callback_response`.

After each test that changes settings, restore the previous configuration:

Restore the application’s daily and monthly volume limits.
Resume the application if you paused it for the test.
Restore the country blocklist, which applies to every OTP application in the account.
Restore the callback URL and the response returned by your callback endpoint.

For every code and status, see Errors and status codes.

Moving to production#

Important

The test numbers listed on this page provide fixed codes and simulated outcomes only in sandbox. In production, verification requests follow the normal delivery rules.

Before going live:

Switch your integration to the production environment. For REST API requests, use https://verification.didww.com as the base URL.
Use the key and secret from a production OTP application.
Keep automated tests that use test numbers configured for the sandbox environment.