Sandbox & Test Data

Didit’s sandbox is the equivalent of Stripe’s test cards or Sumsub’s document templates: it lets you reproduce any verification outcome deterministically, without touching real providers, real PII, or your balance.

The source of truth for this data is serialize_catalog() in the verification service, served live at GET /v1/sandbox/scenarios/. A drift-tested copy is generated into docs/sandbox/SANDBOX_REFERENCE.md in the service-didit-verification repo via pipenv run python scripts/generate_sandbox_reference.py. This page mirrors that reference — always trust the live catalog endpoint if anything here looks stale.

Environment model

Sandbox is a per-application mode (ApplicationDetail.mode == SANDBOX), the same idea as Stripe test mode. While a session runs under a sandbox application:

Every external provider (OCR, AML, face match, liveness, NFC, phone, email, IP, POA, database validation, document AI) is mocked — no third party is ever called.
Sessions are never billed and the balance check is bypassed.
A per-application quota of 500 session creates / 24h is enforced.
Webhooks carry "environment": "sandbox" (live sessions carry "environment": "live").
The hosted flow exposes the session environment so the UI can warn users not to upload real PII.
Outcomes never depend on the pixels: extracted data and statuses come from the scenario / magic value. The captured media itself (documents, selfie, video, POA files) is stored for real, exactly like a live session.

How to switch between live and sandbox

Live and sandbox are separate applications, so test traffic and production data never mix. Each application has a mode of live or sandbox:

Use a sandbox-mode application’s API key to get mocked, unbilled, simulatable sessions.
Use a live-mode application’s API key for real verifications.

The sandbox_scenario field on session create and the simulate endpoints are only accepted on sandbox applications; they are rejected on live applications.

Sandbox in the hosted verification flow

Sessions created under a sandbox application render extra UI in the hosted verification flow (the url returned by POST /v3/session/):

In-card sandbox banner. Every screen shows a banner inside the card - “Test data only - no real calls” - so it is always obvious the session never calls real providers and never touches your balance. Captured media is stored like any session, so use the sample documents and test data rather than real identity documents or personal information.
Pre-flow scenario picker. Before capture starts, an in-card picker walks the user through choosing a test result: pick an outcome, then a trigger for that outcome. Confirming calls POST /v3/session/{session_id}/sandbox/arm/ (see Arm (or re-arm) the session before the flow starts below), then continues into the flow with that scenario’s magic values already applied.
Sample documents strip. A single row of sandbox sample documents (up to 3) sits directly below the document upload/capture component. Tap one to use it instead of a real upload.

Sandbox sessions store the real captured media - documents, selfie, liveness video, and proof-of-address files are uploaded and retained exactly as they would be for a live session. The extracted data (ID verification fields, face match scores, liveness results, and similar) and the session outcome itself (Approved / In Review / Declined) are simulated by the scenario or magic value - never derived from the captured media. The Business Console marks the extracted-data sections of a sandbox session with a Simulated data chip, so reviewers can tell at a glance which parts of the session are the real capture and which are scenario-driven.

Scenarios

Each scenario is a named bundle of magic values. Pass its slug as sandbox_scenario on session create (or to the simulate endpoint) to reproduce the outcome.

Slug	Title	Default status	Description
`approve`	Happy path — all features approve	Approved	Default sandbox behaviour: every mocked feature returns its clean APPROVED outcome. Session status ends as APPROVED.
`decline_aml_hit`	AML — politically exposed person	Declined	AML mock returns one hit and the session declines on the AML feature. The hit uses the same Hit schema as live AML providers — `url`, `match_score`, `risk_score`, `review_status`, `properties`, `pep_matches[]`, and `score_breakdown` are all populated — and a POSSIBLE_MATCH_FOUND warning Log is written.
`decline_document_expired`	ID Verification — document expired	Declined	The ID verification mock returns a passport whose expiry date is in the past. The session declines on ID verification with a DOCUMENT_EXPIRED warning Log.
`decline_minimum_age`	ID Verification — under the minimum age policy	Declined	The ID verification mock returns a DOB making the user roughly 10 years old. Production age check emits MINIMUM_AGE_NOT_MET and the workflow declines.
`decline_mrz_validation`	ID Verification — MRZ checksum failure	Declined	The ID verification mock returns a passport with a corrupted MRZ checksum. Production MRZ validator emits MRZ_VALIDATION_FAILED and the session declines.
`decline_could_not_recognize_document`	ID Verification — unreadable document	Declined	The ID verification mock returns an empty response. Production raises COULD_NOT_RECOGNIZE_DOCUMENT and surfaces it to the SDK.
`decline_face_match_low_similarity`	Face match — similarity below decline threshold	Declined	Face match mock returns a low score. Production emits LOW_FACE_MATCH_SIMILARITY and the workflow node action mapping declines.
`decline_database_no_match`	Database validation — no match across all services	Declined	Every selected database service returns NO_MATCH. Production emits DATABASE_VALIDATION_NO_MATCH and the workflow declines.
`decline_phone_high_risk`	Phone — Twilio reserved high-risk number	Declined	Prelude mock blocks the verification (Twilio reserved range). Phone verification ends as BLOCKED and emits HIGH_RISK_PHONE_NUMBER.
`decline_email_breach`	Email — HIBP breach hit	Declined	HIBP mock returns one breach hit on the address. Email verification emits BREACHED_EMAIL_DETECTED.
`decline_ip_blocklist`	IP analysis — IP address in blocklist	Declined	IP analysis mock declines the location with IP_ADDRESS_IN_BLOCKLIST. Session declines on IP analysis.
`decline_poa_address_mismatch`	POA — address mismatch with provided	Declined	POA mock declines the proof-of-address with ADDRESS_MISMATCH_WITH_PROVIDED. Session declines on POA.
`decline_liveness_attack`	Liveness — face attack detected	Declined	Passive liveness mock detects a face-attack signal and emits LIVENESS_FACE_ATTACK. Session declines on liveness.
`decline_nfc_chip_not_verified`	NFC — ePassport chip not verified	Declined	ePassport mock returns a chip whose SOD/DG signature fails integrity. Production emits NFC_CHIP_NOT_VERIFIED and the session declines on NFC when the workflow declines on unverified chips.
`decline_nfc_trust_anchor_missing`	NFC — issuing trust anchor unavailable	Declined	ePassport mock returns a chip signed by a DSC whose issuing CSCA is absent from the trust store. Production emits NFC_TRUST_ANCHOR_MISSING and the session declines when the workflow declines on unverified chips.
`decline_document_ai_unreadable`	Document AI — unreadable document	Declined	Document AI mock returns no readable fields. Production emits DOCUMENT_AI_UNREADABLE_DOCUMENT and the document settles as declined once the retry budget is exhausted.
`review_aml_possible_match`	AML — possible match needs review	In Review	AML mock returns a lower-confidence hit. The session lands In Review with a warning-level POSSIBLE_MATCH_FOUND Log for an analyst to resolve.
`review_face_match_borderline`	Face match — borderline similarity	In Review	Face match mock returns a score between the review and decline thresholds. The session lands In Review on face match.
`review_document_borderline_age`	ID Verification - underage sent to review	In Review	The ID verification mock returns a DOB under the workflow’s configured minimum age. The workflow’s minimum_age_action is set to REVIEW rather than DECLINE, so the session lands In Review on ID verification instead of declining.
`review_poa_partial_match`	POA — partial address match	In Review	POA mock returns an address that only partially matches the provided one. The session lands In Review on proof of address.
`review_database_partial_match`	Database validation — partial match	In Review	Database services return partial matches on name and date of birth. The session lands In Review on database validation.
`decline_kyb_registry_mismatch`	KYB - registry data mismatch	Declined	Registry mock returns a company whose registration data mismatches the expected details. The business session declines on the registry check.
`review_kyb_registry_partial`	KYB - registry data partially matches	In Review	Registry mock returns a company whose name only partially matches. The business session lands In Review on the registry check.

review_* scenarios exist so you can test manual-review UX (the console review queue, In Review webhooks, reviewer approve/decline actions) without needing a decline-grade input. The two kyb_* scenarios above set expected_details.registration_number instead of expected_details.first_name: they only apply to Business Verification (KYB) sessions.

Magic values

A magic value is a specific input that makes one mocked feature emit a specific risk. Set the input field to the magic value (directly, or via a scenario) to trigger it.

Feature	Input field	Magic value	Risk	Description
AML	`user_email`	`sandbox+aml_hit@didit.test`	`POSSIBLE_MATCH_FOUND`	AML — politically exposed person; AML mock returns one hit, session declines on AML.
ID_VERIFICATION	`expected_details.first_name`	`SANDBOX_OCR_DOCUMENT_EXPIRED`	`DOCUMENT_EXPIRED`	OCR — document expired; session declines on ID verification.
ID_VERIFICATION	`expected_details.first_name`	`SANDBOX_OCR_MINIMUM_AGE_NOT_MET`	`MINIMUM_AGE_NOT_MET`	OCR — date of birth makes the user below the configured minimum age; session declines.
ID_VERIFICATION	`expected_details.first_name`	`SANDBOX_OCR_MAXIMUM_AGE_EXCEEDED`	`MAXIMUM_AGE_EXCEEDED`	OCR — extracted DOB exceeds the configured maximum age policy.
ID_VERIFICATION	`expected_details.first_name`	`SANDBOX_OCR_DOCUMENT_NUMBER_FORMAT_MISMATCH`	`DOCUMENT_NUMBER_FORMAT_MISMATCH`	OCR — extracted document number does not match the document’s expected format regex from the document registry.
ID_VERIFICATION	`expected_details.first_name`	`SANDBOX_OCR_PERSONAL_NUMBER_FORMAT_MISMATCH`	`PERSONAL_NUMBER_FORMAT_MISMATCH`	OCR — extracted personal number fails the document registry’s format check.
ID_VERIFICATION	`expected_details.first_name`	`SANDBOX_OCR_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`	`DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`	OCR — extracted document type is outside the application’s `documents_allowed` policy.
ID_VERIFICATION	`expected_details.first_name`	`SANDBOX_OCR_FULL_NAME_MISMATCH_WITH_PROVIDED`	`FULL_NAME_MISMATCH_WITH_PROVIDED`	OCR — name on the document doesn’t match the name the customer prefilled in `expected_details` above the name-match threshold.
ID_VERIFICATION	`expected_details.first_name`	`SANDBOX_OCR_GENDER_MISMATCH_WITH_PROVIDED`	`GENDER_MISMATCH_WITH_PROVIDED`	OCR — extracted gender disagrees with `expected_details.gender`.
ID_VERIFICATION	`expected_details.first_name`	`SANDBOX_OCR_DOB_MISMATCH_WITH_PROVIDED`	`DOB_MISMATCH_WITH_PROVIDED`	OCR — extracted date of birth disagrees with `expected_details.date_of_birth`.
ID_VERIFICATION	`expected_details.first_name`	`SANDBOX_OCR_COUNTRY_MISMATCH_WITH_PROVIDED`	`COUNTRY_MISMATCH_WITH_PROVIDED`	OCR — issuing state disagrees with `expected_details.country` (or `id_country`).
ID_VERIFICATION	`expected_details.first_name`	`SANDBOX_OCR_NATIONALITY_MISMATCH_WITH_PROVIDED`	`NATIONALITY_MISMATCH_WITH_PROVIDED`	OCR — extracted nationality disagrees with `expected_details.nationality`.
ID_VERIFICATION	`expected_details.first_name`	`SANDBOX_OCR_IDENTIFICATION_NUMBER_MISMATCH_WITH_PROVIDED`	`IDENTIFICATION_NUMBER_MISMATCH_WITH_PROVIDED`	OCR — extracted document/personal/tax number doesn’t match `expected_details.identification_number`.
ID_VERIFICATION	`expected_details.first_name`	`SANDBOX_OCR_COULD_NOT_RECOGNIZE_DOCUMENT`	`COULD_NOT_RECOGNIZE_DOCUMENT`	OCR pipeline returns empty / unrecognizable; production raises COULD_NOT_RECOGNIZE_DOCUMENT.
ID_VERIFICATION	`expected_details.first_name`	`SANDBOX_OCR_MRZ_NOT_DETECTED`	`MRZ_NOT_DETECTED`	OCR — document expects an MRZ but the pipeline could not locate one.
ID_VERIFICATION	`expected_details.first_name`	`SANDBOX_OCR_MRZ_VALIDATION_FAILED`	`MRZ_VALIDATION_FAILED`	OCR — MRZ was found but failed checksum / format validation.
ID_VERIFICATION	`expected_details.first_name`	`SANDBOX_OCR_MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME`	`MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME`	OCR — MRZ identity fields disagree with VIZ-extracted fields.
ID_VERIFICATION	`expected_details.first_name`	`SANDBOX_OCR_BARCODE_NOT_DETECTED`	`BARCODE_NOT_DETECTED`	OCR — document expects a barcode but none was found.
ID_VERIFICATION	`expected_details.first_name`	`SANDBOX_OCR_BARCODE_VALIDATION_FAILED`	`BARCODE_VALIDATION_FAILED`	OCR — barcode was decoded but failed cross-field validation.
ID_VERIFICATION	`expected_details.first_name`	`SANDBOX_OCR_QR_NOT_DETECTED`	`QR_NOT_DETECTED`	OCR — document expects a QR code but none was found.
ID_VERIFICATION	`expected_details.first_name`	`SANDBOX_OCR_QR_VALIDATION_FAILED`	`QR_VALIDATION_FAILED`	OCR — QR code was decoded but failed cross-field validation.
ID_VERIFICATION	`expected_details.first_name`	`SANDBOX_OCR_DATA_INCONSISTENT`	`DATA_INCONSISTENT`	OCR — internal consistency checks on VIZ fields disagree.
ID_VERIFICATION	`expected_details.first_name`	`SANDBOX_OCR_DOCUMENT_SIDES_MISMATCH`	`DOCUMENT_SIDES_MISMATCH`	OCR — front and back document_name do not pair as the same document.
ID_VERIFICATION	`expected_details.first_name`	`SANDBOX_OCR_NAME_NOT_DETECTED`	`NAME_NOT_DETECTED`	OCR — neither first nor last name could be extracted from the document.
ID_VERIFICATION	`expected_details.first_name`	`SANDBOX_OCR_DATE_OF_BIRTH_NOT_DETECTED`	`DATE_OF_BIRTH_NOT_DETECTED`	OCR — document class expects a DOB but extraction returned none.
ID_VERIFICATION	`expected_details.first_name`	`SANDBOX_OCR_EXPIRATION_DATE_NOT_DETECTED`	`EXPIRATION_DATE_NOT_DETECTED`	OCR — document class expects an expiry date but extraction returned none.
ID_VERIFICATION	`expected_details.first_name`	`SANDBOX_OCR_DOCUMENT_NUMBER_NOT_DETECTED`	`DOCUMENT_NUMBER_NOT_DETECTED`	OCR — neither document number nor personal number could be extracted.
ID_VERIFICATION	`expected_details.first_name`	`SANDBOX_OCR_COULD_NOT_DETECT_DOCUMENT_TYPE`	`COULD_NOT_DETECT_DOCUMENT_TYPE`	OCR — classifier could not map the capture to a supported document type.
ID_VERIFICATION	`expected_details.first_name`	`SANDBOX_OCR_PORTRAIT_IMAGE_NOT_DETECTED`	`PORTRAIT_IMAGE_NOT_DETECTED`	OCR — pipeline could not isolate a portrait region on the document.
ID_VERIFICATION	`expected_details.first_name`	`SANDBOX_OCR_UNPARSED_ADDRESS`	`UNPARSED_ADDRESS`	OCR — document has an address field but geocoding / parsing returned nothing usable.
DATABASE_VALIDATION	`expected_details.first_name`	`SANDBOX_DB_NO_MATCH`	`DATABASE_VALIDATION_NO_MATCH`	Database validation — every government/registry service returns NO_MATCH; session declines on database validation.
FACEMATCH	`expected_details.first_name`	`SANDBOX_FACE_LOW_MATCH`	`LOW_FACE_MATCH_SIMILARITY`	Face match — similarity score below the decline threshold; session declines on face match.
PHONE	`phone_number`	`+15005550009`	`HIGH_RISK_PHONE_NUMBER`	Phone — Twilio-style undeliverable / high-risk number; phone verification mock returns failure.
EMAIL	`user_email`	`sandbox+breach@didit.test`	`BREACHED_EMAIL_DETECTED`	Email — HIBP returns a breach hit on this address.
LOCATION	`expected_details.first_name`	`SANDBOX_IP_BLOCKLIST`	`IP_ADDRESS_IN_BLOCKLIST`	IP analysis — caller IP appears in the application blocklist; session declines on IP analysis.
PROOF_OF_ADDRESS	`expected_details.first_name`	`SANDBOX_POA_ADDRESS_MISMATCH`	`ADDRESS_MISMATCH_WITH_PROVIDED`	POA — address on uploaded document disagrees with the address the customer prefilled in `expected_details`; session declines on POA.
LIVENESS	`expected_details.first_name`	`SANDBOX_LIVENESS_ATTACK`	`LIVENESS_FACE_ATTACK`	Liveness — passive liveness mock detects a face-attack signal; session declines on liveness.
NFC	`expected_details.first_name`	`SANDBOX_NFC_CHIP_NOT_VERIFIED`	`NFC_CHIP_NOT_VERIFIED`	NFC — ePassport mock returns a chip whose SOD/DG signature fails integrity; production emits NFC_CHIP_NOT_VERIFIED and declines when the workflow declines on unverified chips.
NFC	`expected_details.first_name`	`SANDBOX_NFC_TRUST_ANCHOR_MISSING`	`NFC_TRUST_ANCHOR_MISSING`	NFC — the DSC chains to a CSCA absent from the trust store; production emits NFC_TRUST_ANCHOR_MISSING and applies the configured unverified-chip action.
DOCUMENT_AI	`expected_details.first_name`	`SANDBOX_DOCUMENT_AI_UNREADABLE`	`DOCUMENT_AI_UNREADABLE_DOCUMENT`	Document AI — extraction returns no readable fields; production emits DOCUMENT_AI_UNREADABLE_DOCUMENT and the document settles as declined once the retry budget is exhausted.
AML	`user_email`	`sandbox+aml_review@didit.test`	`POSSIBLE_MATCH_FOUND`	AML — possible match that needs manual resolution; session lands In Review.
FACEMATCH	`expected_details.first_name`	`SANDBOX_FACE_BORDERLINE_MATCH`	`LOW_FACE_MATCH_SIMILARITY`	Face match — borderline similarity between review and decline thresholds; session lands In Review.
ID_VERIFICATION	`expected_details.first_name`	`SANDBOX_OCR_BORDERLINE_AGE`	`MINIMUM_AGE_NOT_MET`	OCR — date of birth is below the minimum age but the workflow reviews rather than declines minimum-age failures; session lands In Review.
DATABASE_VALIDATION	`expected_details.first_name`	`SANDBOX_DB_PARTIAL_MATCH`	`DATABASE_VALIDATION_PARTIAL_MATCH`	Database validation — identification matches but name/DOB only partially; session lands In Review.
PROOF_OF_ADDRESS	`expected_details.first_name`	`SANDBOX_POA_PARTIAL_MATCH`	`ADDRESS_MISMATCH_WITH_PROVIDED`	POA — address on uploaded document partially matches the provided address; session lands In Review.
KYB_REGISTRY	`expected_details.registration_number`	`SANDBOX-KYB-MISMATCH`	`KYB_REGISTRY_DATA_MISMATCH_WITH_EXPECTED`	KYB - registry company data mismatches the expected details; session declines.
KYB_REGISTRY	`expected_details.registration_number`	`SANDBOX-KYB-REVIEW`	`KYB_REGISTRY_DATA_PARTIAL_MATCH_WITH_EXPECTED`	KYB - registry company data partially matches; session lands In Review.

The sample documents

Never upload real identity documents in sandbox. Use the built-in sample documents instead.

The hosted flow offers three sample documents, one per document type:

Country	Document type
Spain	National ID card
Argentina	Passport
Poland	Driver’s license

Tap a sample in the strip to use it instead of a real capture. The extracted data and the session outcome always come from the selected scenario or magic value, so any sample works with any scenario.

Sample identity: testing `expected_details`

Every sandbox document is fabricated from one pinned identity. The extracted values are the same on every session and are never derived from the current date, so you can prefill expected_details with them and check your field-comparison and warning handling end to end. Pass the values below and the comparison checks pass; pass anything else and the matching *_MISMATCH_WITH_PROVIDED warning fires on purpose. Dates are shared by every sample document:

Field	Value
`date_of_birth`	`1990-06-15`
Date of issue	`2025-06-15`
Date of expiry	`2035-06-15`

The rest of the identity depends on which document you use:

`sandbox_sample`	Document	`first_name`	`last_name`	`gender`	`nationality`	`id_country`	`identification_number`
(default, no sample selected)	Brazil ePassport	`GUSTAVO`	`MATSUMOTO`	`M`	`BRA`	`BRA`	`YC531181`
`spain-id-card-2021`	Spain national ID card	`CARMEN`	`ESPAÑOLA ESPAÑOLA`	`F`	`ESP`	`ESP`	`CAA000000`
`argentina-passport-2009`	Argentina passport	`MARIA VICTORIA`	`VILLAREAL`	`F`	`ARG`	`ARG`	`AAF794880`
`poland-driving-license-2019`	Poland driver’s license	`JAN`	`KOWALSKI`	not on this document	`POL`	`POL`	`SP005/89/5`

{
  "workflow_id": "<your-workflow-uuid>",
  "expected_details": {
    "date_of_birth": "1990-06-15",
    "gender": "M",
    "nationality": "BRA",
    "identification_number": "YC531181"
  }
}

first_name and last_name are the exception: the sandbox echoes the names you send in expected_details onto the fabricated document, so name matching passes with any name. Use the SANDBOX_OCR_FULL_NAME_MISMATCH_WITH_PROVIDED magic value to exercise a name mismatch, and SANDBOX_OCR_DOB_MISMATCH_WITH_PROVIDED for a date-of-birth mismatch.

If your workflow restricts documents_allowed to a country or document type that excludes the Brazil ePassport, the sandbox fabricates a document from the first allowed country instead, so nationality, id_country, and the document name follow that country. The dates above stay the same.

OTP codes and email opt-in

Phone OTP: the sandbox phone check accepts any well-formed code (4-8 digits; 123456 included). Malformed input still returns 400.
Email OTP: the sandbox email check accepts any well-formed code (123456 included). Malformed input still returns 400.

By default sandbox sessions do not send emails (review alerts, status change, OTP, resubmit, new-session-link, etc.). To deliver an email anyway, use one of these opt-in patterns on the recipient address:

Opt-in pattern	Example
`<local>+sandbox@<domain>`	`alice+sandbox@example.com`
`*@didit.test`	`alice@didit.test`

Driving outcomes: scenarios, magic values, arming, and the simulate endpoint

There are four ways to control a sandbox session’s outcome.

1. `sandbox_scenario` at session create

Set the scenario slug when creating the session (POST /v3/session/). The create flow expands the scenario’s bundled magic values into the session’s input fields, so the mocked providers emit the intended outcome through the real workflow pipeline.

{
  "workflow_id": "<your-workflow-uuid>",
  "sandbox_scenario": "decline_document_expired"
}

2. Magic values typed by hand

Set the individual input fields yourself (for example expected_details.first_name = "SANDBOX_OCR_DOCUMENT_EXPIRED", or user_email = "sandbox+aml_hit@didit.test"). See the magic values table above for the full registry.

3. Arm (or re-arm) the session before the flow starts

Set or replace the armed scenario on a session that already exists, as long as it hasn’t progressed past Not Started. This is the endpoint the pre-flow scenario picker calls, and you can call it yourself to build a custom picker or test harness:

POST /v3/session/{session_id}/sandbox/arm/
Session-Token: <session_token>

{
  "scenario": "decline_document_expired"
}

200 response:

{
  "session_id": "<session_id>",
  "scenario": "decline_document_expired",
  "status": "Not Started"
}

Authenticate with the session’s own Session-Token (returned as session_token from session create), not your application API key: this is a client-facing endpoint.
Returns 400 for an unknown scenario slug, and 400 once the session has moved past Not Started ("Scenario can only be armed before the verification starts.").
Returns 404 when the Session-Token belongs to a live (non-sandbox) application, or doesn’t match the session_id in the path.
Re-arming replaces the previous scenario. It clears only the magic values the previous scenario wrote, and leaves anything the user already typed by hand (email, first name, etc.) untouched. For example: arm decline_phone_high_risk, then arm approve - the phone number reverts to unset, but a customer-entered email survives both calls.

4. The simulate endpoint

Force a terminal status after the fact:

Console / API key (requires the write:sessions privilege): POST /v3/session/{session_id}/simulate/
Hosted flow (Session-Token header): POST /v3/session/{session_id}/sandbox/simulate/

Body fields: new_status, scenario, risk, comment, node_id — all optional, but at least one of new_status, scenario, or risk is required. When only scenario or risk is given, new_status defaults to that scenario’s / risk’s default status, and the matching warning Log is written.

{
  "scenario": "decline_aml_hit"
}

Where `sandbox_scenario` appears

The armed scenario slug (null if none is armed) is echoed back on some surfaces and intentionally left off others:

Surface	Exposed?
Current step payload (KYC and KYB)	Yes, as `sandbox_scenario`
`GET /v1/session/{id}/decision/`	Yes, as `sandbox_scenario`
`GET /v3/session/{id}/decision/` (see Retrieve Session)	Yes, top-level `sandbox_scenario` (null when unarmed)
Session webhooks (`status.updated`, `data.updated`)	Yes, as `sandbox_scenario`, `null` on live sessions or unarmed sandbox sessions

If your integration needs to branch on the armed scenario server-side, read it from the webhook envelope or either decision endpoint (v1 or v3).

Usage and billing

Sandbox usage is tracked, never charged:

Every mocked call still records a usage event (is_sandbox: true, priced at 0.0000) so sandbox volume is visible for debugging, but it is never added to your usage totals, never decremented from balance, and never appears on an invoice.
The Business Console’s balance, top-up, and live-usage surfaces filter sandbox usage out by default. The top-up usage endpoints accept an environment parameter (live, the default, or sandbox) so sandbox volume can be inspected separately - always at zero cost and with no free-tier consumption.
Email and phone verification bill per request rather than per session outcome, and sandbox has no way to fully mirror that at the webhook layer. Sandbox email/phone checks still record a usage event per request at price 0.0000, same as every other mocked feature: this is an accepted, known divergence from live billing behavior, not a bug.
Database validation’s response shape in sandbox intentionally diverges from the live per-provider shape, since there is no real provider to mirror. Treat sandbox database-validation payloads as a stand-in for the outcome (status and warning code), not a byte-for-byte preview of a live provider response.

Guides

Model Context Protocol (MCP)

Web SDKs

Native SDKs

Integrations

Environment model

How to switch between live and sandbox

Sandbox in the hosted verification flow

Scenarios

Magic values

The sample documents

Sample identity: testing `expected_details`

OTP codes and email opt-in

Driving outcomes: scenarios, magic values, arming, and the simulate endpoint

1. `sandbox_scenario` at session create

2. Magic values typed by hand

3. Arm (or re-arm) the session before the flow starts

4. The simulate endpoint

Where `sandbox_scenario` appears

Usage and billing

​Environment model

​How to switch between live and sandbox

​Sandbox in the hosted verification flow

​Scenarios

​Magic values

​The sample documents

​Sample identity: testing expected_details

​OTP codes and email opt-in

​Driving outcomes: scenarios, magic values, arming, and the simulate endpoint

​1. sandbox_scenario at session create

​2. Magic values typed by hand

​3. Arm (or re-arm) the session before the flow starts

​4. The simulate endpoint

​Where sandbox_scenario appears

​Usage and billing

Environment model

How to switch between live and sandbox

Sandbox in the hosted verification flow

Scenarios

Magic values

The sample documents

Sample identity: testing `expected_details`

OTP codes and email opt-in

Driving outcomes: scenarios, magic values, arming, and the simulate endpoint

1. `sandbox_scenario` at session create

2. Magic values typed by hand

3. Arm (or re-arm) the session before the flow starts

4. The simulate endpoint

Where `sandbox_scenario` appears

Usage and billing