> For the complete documentation index, see [llms.txt](https://docs.idlayr.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.idlayr.com/get-started/sandbox-testing.md).

# Sandbox testing

Sandbox is a project mode that lets you exercise every response path of every IDlayr product without contacting a real mobile network. Each call is intercepted by IDlayr, and the response is fabricated based on the input you pass — typically the last digits of an MSISDN, or in some cases the last digits of an IP address.

The response shape is identical to production: same fields, same error codes, same callback delivery. Your integration code doesn't need to branch on environment.

For the conceptual model (sandbox vs production, when to use which), see [Project modes](/get-started/concepts/project-modes.md).

## Enabling sandbox

Sandbox is set at **project creation**. You can't toggle it in place — moving from sandbox to production means creating a separate production project, which keeps test traffic and live traffic visibly separate in analytics and approvals.

Create a sandbox project in the Enterprise Portal. The same OAuth2 client-credentials flow applies; the project's `client_id` and `client_secret` drive sandbox routing — no special header or base URL.

## Outcomes are driven by input suffixes

In sandbox, IDlayr picks the simulated outcome by inspecting the last digits of your input:

* **Phone-number-input products** (Secure SNA, SIM Swap, Reverse SMS, Eligibility by phone number) use the last digit(s) of the submitted MSISDN.
* **IP-input products** (Eligibility by mobile IP address) use the last digit(s) of the submitted IP address.
* **Discovery** does not currently support sandbox mode — Discovery takes no input from the caller that the sandbox can key off. Follow ENG-1457 for progress.

The pattern is consistent across products: even/odd last digit usually drives the primary outcome, and specific two-digit suffixes (`00`, `55`, `99`) drive error states.

## Per-product suffix maps

### Secure SNA

| MSISDN ends with                     | `match` | `status`    |
| ------------------------------------ | ------- | ----------- |
| Even digit (`0`, `2`, `4`, `6`, `8`) | `true`  | `COMPLETED` |
| Odd digit (`1`, `3`, `5`, `7`, `9`)  | `false` | `COMPLETED` |
| `00`, `55`, `99`                     | —       | `ERROR`     |

See [Secure SNA — Testing in sandbox](/products/number-verification/secure-sna/testing.md) for iOS Wi-Fi sandbox mode and Android emulator detection.

### SIM Swap

| MSISDN ends with | `no_sim_change` | `status`    |
| ---------------- | --------------- | ----------- |
| `0`–`4`          | `true`          | `COMPLETED` |
| `5`–`9`          | `false`         | `COMPLETED` |
| `00`, `55`, `99` | —               | `ERROR`     |

See [SIM Swap — Testing in sandbox](/products/risk/sim-swap/testing.md) for product-specific notes.

### Eligibility — by Mobile IP Address

| IP ends with           | HTTP status | Meaning                 |
| ---------------------- | ----------- | ----------------------- |
| Even last digit        | 200         | Success, eligible       |
| Odd last digit         | 412         | Not a mobile IP address |
| `99` (last two digits) | 400         | MNO not supported       |

### Eligibility — by Phone Number

Phone-number sandbox values follow the conventional MSISDN-suffix pattern used across IDlayr products (even/odd last digit drives match/no-match; `00`, `55`, `99` drive error states). The specific outcome values for the v1 phone-number endpoint will be confirmed at onboarding.

See [Eligibility — Testing in sandbox](/products/eligibility/testing.md) for product-specific notes.

### Reverse SMS

| MSISDN ends with                     | `match` | `status`    |
| ------------------------------------ | ------- | ----------- |
| Even digit (`0`, `2`, `4`, `6`, `8`) | `true`  | `COMPLETED` |
| Odd digit (`1`, `3`, `5`, `7`, `9`)  | `false` | `COMPLETED` |
| `00`, `55`, `99`                     | —       | `ERROR`     |

See [Reverse SMS — Testing in sandbox](/products/number-verification/reverse-sms/testing.md) for notes on testing the native SMS-composer step.

### Discovery

Discovery does not currently support sandbox mode. The platform's sandbox behaviour keys off the phone number the caller submits, and Discovery Check takes no phone number on Create (that's what it discovers). A follow-up to add sandbox support for Discovery is tracked as ENG-1457.

For integration testing until sandbox support lands, use a production project against a real device on a supported cellular network. See [Discovery — Prerequisites](/products/number-verification/discovery/prerequisites.md).

## Platform-specific notes

### iOS — sandbox Wi-Fi mode

In production, the iOS SDK requires a cellular data connection for Secure SNA. For sandbox projects, the SDK can be configured to allow requests over Wi-Fi — useful for simulators and devices without a SIM:

```swift
let sdk = IDlayrSDK(isSandbox: true)
```

{% hint style="warning" %}
`isSandbox: true` is for sandbox projects only. Production apps must use the default (`false`). A production project will reject the request if the SDK is initialised with `isSandbox: true`.
{% endhint %}

### Android — emulator sandbox mode

The Android SDK supports sandbox testing on emulators. When the SDK detects an emulator environment, it automatically:

* Skips cellular network binding (emulators have no cellular radio).
* Falls back to the emulator's default network (Wi-Fi).
* Sends the `x-idlayr-mode: sandbox` header on outbound HTTP requests.

This works only on emulators, not on physical devices. Physical-device sandbox support is on the roadmap.

## What sandbox does and doesn't simulate

### Sandbox simulates

* Successful and failed verifications across every product.
* Specific error codes and terminal-status values.
* Callback delivery, including JWKS signature verification.
* The shape and timing of state transitions.

### Sandbox does not simulate

* Real device-to-carrier signal paths or carrier-specific behaviour.
* Production latency variance.
* Carrier-specific edge cases that production traffic surfaces — line type, MVNO, prepaid behaviour, regional regulatory restrictions.

### Sandbox retention

* Sandbox checks that resolve to `EXPIRED` or `ERROR` **are not persisted**. Listing checks via the API will not return them.
* Sandbox checks **do not hit MNOs** and **do not consume billed API balance**.

## When to graduate to production

Use sandbox for development, CI integration tests, and demonstrating flows to internal stakeholders. Before going live:

1. Confirm the use case has gone through IDlayr's approval flow.
2. Run a small set of production checks against real numbers in your target markets, particularly to validate carrier coverage. Sandbox responses follow the spec; production responses depend on the carrier's actual behaviour at the time.
3. Create a separate production project — don't share credentials between sandbox and production.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.idlayr.com/get-started/sandbox-testing.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.