> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prelude.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Test Numbers

> Learn how to confirm that your integration is working properly by simulating verifications without incurring charges using special test numbers.

Test numbers are special phone numbers you register on your account that never reach a real carrier. When you create a verification against a test number, Prelude short-circuits the flow: no message is sent, no cost is incurred, and the code is a fixed value you set when creating the number. Reach for them in automated integration tests and during local development, any time you want to exercise the end-to-end Verify flow without touching production messaging.

Test numbers let you simulate:

* Successful verification flows
* Anti-fraud outcomes: `challenged`, `blocked` and `shadow_blocked`, with each blocking reason
* [Silent Verification](#silent-verification), both the silent success and the fallback to a message
* Errors due to invalid codes, expired verifications or too many attempts

# Responses

Each test number carries a `response` that decides what the API answers for a verification against it.
The default, `valid`, is the successful flow above. The other responses let you exercise every branch of
your integration, including the ones that are hard to reach with a real number:

| Response | Create | Check |
| - | - | - |
| `valid` | `success` | accepts the attempt code |
| `challenged` | `challenged`, channels without SMS or voice | accepts the attempt code |
| `blocked_<reason>` | `blocked` with that `reason` | not reachable |
| `shadow_blocked_<reason>` | `shadow_blocked` with that `reason` | accepts the attempt code |
| `silent_verified` | `method: silent` | accepts the code the silent flow returned |
| `silent_mismatch` | `method: silent`, the silent flow fails; the next Create returns `retry` with `method: message` | accepts the attempt code |
| `expired` | `success` | `expired_or_not_found`, whatever the code |

`<reason>` is one of `suspicious`, `repeated_attempts`, `invalid_phone_line`, `invalid_phone_number`,
`in_block_list`, `invalid_signature` and `expired_signature`, exactly as the
[Create verification](https://docs.prelude.so/verify/v2/api-reference/create-or-retry-a-verification.md) response reports it.

`blocked_<reason>` and `expired` never check a code, so those numbers need no attempt code. A test number can
also carry a short description, shown under the number on the dashboard.

## Silent Verification

The `silent_verified` and `silent_mismatch` responses simulate
[Silent Verification](https://docs.prelude.so/verify/v2/documentation/silent-verification.md) without any carrier involved. A
verification created against such a number returns `"method": "silent"` with a `request_url`, exactly as a
real eligible number would. The SDK follows that URL and receives either the attempt code or a failure. A
test number on any other response is never offered the silent method, which lets you test the fallback
branch too.

> [!WARNING]
>
> The device still needs an active cellular connection: the frontend SDKs always send the silent request
> over the cellular interface. Failures that happen on the device before the request leaves it (no cellular
> data, timeouts) cannot be simulated with a test number.

# How to use test numbers

To create a test number, go to **Verify API > Configure > Numbers** on the Dashboard and click **Add Number**
in the **Sandboxed Numbers** section. Then fill in:

* **Phone Number**: the E.164 number to sandbox.
* **API Response**: one of the [responses](#responses) above. Defaults to `valid`.
* **Attempt Code**: the only code the **Check** endpoint accepts for this number, 4 to 8 characters. Not
  asked for `blocked_<reason>` and `expired`, which never check a code.
* **Description**: optional, at most 80 characters, shown under the number in the list.

> [!WARNING]
>
> A code sent in `options.custom_code` is ignored for a test number: only the number's attempt code is
> accepted.

You can also manage test numbers through the
[management API](https://docs.prelude.so/verify/v2/api-reference/management/phone-numbers/sandbox/add-sandbox-phone-number.md), which
takes the same `response` and `description` fields.

![Add Number dialog with the silent\_verified API response selected](https://mintcdn.com/ding/rr1QS7Xoy8RLiukL/images/add-test-number-screenshot.png?fit=max\&auto=format\&n=rr1QS7Xoy8RLiukL\&q=85\&s=70f05a979ded42f20d0bd81bdb985c78)

Add test number modal


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.