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. The catalog endpoint is authenticated: send your API key (x-api-key) the same way you would on any other call, or a session token if you are reading it from inside a running session.

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.

Transaction Monitoring in sandbox

Sandbox is session-shaped: it mocks the providers a verification session would call. Transaction Monitoring has no provider to mock, so a sandbox application takes the other route: the transaction is stored, but nothing that decides, screens, notifies or charges ever runs over it. A transaction created on a sandbox application is persisted and returned as usual, and none of the following happens to it:

No rule evaluation. rule_runs is empty, whatever mode your rules are in. An ACTIVE rule on a sandbox application never fires, so the transaction stays APPROVED with score 0 and no alert or case is opened.
No AML / wallet screening. provider_results is empty even for crypto transactions on an application with monitoring enabled.
No webhooks. Neither transaction.created nor transaction.status.updated is delivered for a sandbox transaction.
No billing. A usage event is recorded at price 0.0000 and your balance is untouched.

Every transaction response carries an environment field ("live" or "sandbox") so an empty rule_runs is never ambiguous: "sandbox" means the rules were not evaluated, not that none of them matched. The Business Console says the same thing in the transaction’s Risk & decision card instead of a bare “No rules evaluated”.

Travel Rule is the one exception to “nothing runs”. On an application with Travel Rule enabled, a sandbox travelRule transaction still runs the exchange engine: the transfer record is created and moves through its statuses. What sandbox never does is talk to anyone - no compliance message reaches a counterparty VASP over any rail (platform network memberships, BYOK, email, or INTERNAL), counterparty VASP attribution screening is skipped, cancellations are a no-op, and travel_rule.status.updated webhooks are not delivered. The two directions then behave differently, because only one of them dispatches:Outbound - a travelRule transaction you submit. The threshold_amount and self-hosted-wallet checks apply as normal, then dispatch is simulated: no rail is selected, so the transfer parks at AWAITING_COUNTERPARTY, exactly like a real send whose rail callbacks have not arrived yet. Nothing advances it from there, so a full two-sided rail loop can only be exercised between live applications.Inbound - POST /v3/travel-rule/inbound/. Registration never dispatches over a rail, so nothing about it is simulated: sandbox resolves the deposit against your wallet address book and settles synchronously, exactly as live does. It resolves to a real outcome rather than AWAITING_COUNTERPARTY - ON_HOLD (no address book match), UNCONFIRMED_OWNERSHIP (matched entry is not ownership-verified), COUNTERPARTY_MISMATCHED_DATA (beneficiary name does not match the wallet holder), or COMPLETED then FINISHED (matched a verified entry). This makes inbound registration the one Travel Rule flow you can exercise end to end in sandbox.

How to exercise a rule before it goes live. Use Backtest: it replays the rule against your real transaction history and reports evaluated / matched / affected_entities without touching any transaction’s status. Pair it with TEST mode on the live application - a TEST rule evaluates on every new live transaction and records what it would have matched, without changing the score or status - and switch to ACTIVE once the selectivity looks right.

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 on the standalone AML API) 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 — reserved high-risk test number	Declined	The phone verification mock blocks the verification (reserved test range). Phone verification ends as BLOCKED and emits HIGH_RISK_PHONE_NUMBER.
`decline_email_breach`	Email — breach-database hit	Declined	The email breach 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 — reserved undeliverable / high-risk test number; phone verification mock returns failure.
EMAIL	`user_email`	`sandbox+breach@didit.test`	`BREACHED_EMAIL_DETECTED`	Email — the breach database returns a 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.

Non-doc lookup and identity wallets

Sandbox applications can enable every identity wallet in the country catalog, including wallets that are unavailable on live applications. The default approve scenario simulates a verified identity without signing in to an external wallet. The result is stored in the session and follows the workflow’s normal next step. Sandbox does not validate a real wallet credential or charge for simulated attempts. Lookup requests still validate the entered fields and use the configured attempt limit, which defaults to one. Use the following scenarios to exercise retries and fallback rules:

Scenario	Simulated result
`lookup_partial_match`	Partial registry match; counts toward the attempt limit.
`lookup_no_match`	Registry answers without a match; counts toward the attempt limit.
`lookup_provider_error`	Registry returns no answer; follows the provider-error fallback.
`wallet_cancelled`	User cancels wallet sign-in.
`wallet_timeout`	Wallet sign-in expires.
`wallet_provider_error`	Wallet cannot complete sign-in.

Wallet failures follow the country setting to fall back to document capture or decline. Completed lookup attempts are recorded separately, so two allowed attempts produce two results before fallback. All sandbox usage remains free.

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.

What the fabricated document does not carry

The fabricated document is the generic template for the allowed country and document type, so the fields that only a real, state-issued document provides stay empty. The one that matters for routing is the region / US state (kyc.region): a sandbox US driver’s license or ID card has no state, so a branch condition such as Region equals IL can never match in sandbox and, when no other branch of that node matches either, the flow takes the node’s fallback branch (the branch with no conditions). This is not a review or a failure of the branch - the condition simply has nothing to read. A missing field also fails not equals and not in; see how branch conditions read session data for the difference between a missing field and an empty string. To exercise a state-dependent flow in sandbox, drive the decision from a value you control on the session rather than from the document:

Send the state in metadata when you create the session (for example "metadata": {"credential_state": "IL"}) and branch on metadata.credential_state. Metadata is evaluated in sandbox exactly as it is live.
Keep the document-derived kyc.region condition for live traffic if you also need the document to prove the state; in live mode the region is read from the real document.

Everything else about routing is identical to live: the workflow graph, branch conditions, metadata and expected_details values, action nodes and status nodes all run for real. Sandbox never forces a session into review on its own - a sandbox session ends In Review only when the workflow routes it there (a review_* scenario, a magic value mapped to a review action, or a status node in the graph).

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 five ways to control a sandbox 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"
}

5. `sandbox_scenario` on the standalone AML API

Back-end AML screening has no end user and no session to arm, so the slug goes on the screening request itself (POST /v3/aml/):

{
  "full_name": "Ada Lovelace",
  "save_api_request": true,
  "sandbox_scenario": "decline_aml_hit"
}

decline_aml_hit returns one production-shaped hit and settles the screening as Declined; review_aml_possible_match settles it In Review. A scenario that arms no AML outcome leaves the screening clean.
With save_api_request: true (the default) the screening is persisted exactly as it is on a live key, so the returned request_id resolves through GET /v3/session/{request_id}/decision/ and GET /v3/session/{request_id}/generate-pdf/.
Returns 400 for an unknown scenario slug, and 400 when the API key belongs to a live application.

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

Transaction Monitoring in sandbox

How to switch between live and sandbox

Sandbox in the hosted verification flow

Scenarios

Magic values

Non-doc lookup and identity wallets

The sample documents

Sample identity: testing `expected_details`

What the fabricated document does not carry

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

5. `sandbox_scenario` on the standalone AML API

Where `sandbox_scenario` appears

Usage and billing

​Environment model

​Transaction Monitoring in sandbox

​How to switch between live and sandbox

​Sandbox in the hosted verification flow

​Scenarios

​Magic values

​Non-doc lookup and identity wallets

​The sample documents

​Sample identity: testing expected_details

​What the fabricated document does not carry

​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

​5. sandbox_scenario on the standalone AML API

​Where sandbox_scenario appears

​Usage and billing

Environment model

Transaction Monitoring in sandbox

How to switch between live and sandbox

Sandbox in the hosted verification flow

Scenarios

Magic values

Non-doc lookup and identity wallets

The sample documents

Sample identity: testing `expected_details`

What the fabricated document does not carry

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

5. `sandbox_scenario` on the standalone AML API

Where `sandbox_scenario` appears

Usage and billing