Sandbox vs live

Every run has an execution_mode: test or live. The mode is chosen per request, not per key, so the same integration moves from sandbox to production by changing one field.

What does test mode do?

• Synthetic data. Nothing calls a billable bureau or vendor and nothing is billed. For most applicants every product node returns its schema mock: happy_path (clean file, no records) by default.
• Pick the outcome with scenario. Add "scenario": "fail_path" to payload to make every product node return its decline mock (for example the eviction node reports two filings and recommendation: FAIL), so fail_steps and adverse-action branches run. A node's mock_scenario config overrides it.
• Registered test subjects replay. When a trigger's applicant is a registered test subject and that subject is registered for every product node in the cascade, the run replays the subject's authored bureau responses instead of the mocks, still at no charge. The execution's input_context.sandbox_replay is true, and scenario has no effect on that run. Any other applicant, and every batch row, gets the mocks.
• Drafts run. A cascade with active: false accepts a single execution_mode: test trigger, so you can exercise it before activating. Batches and re-evaluations still need an active cascade (409 workflow_inactive), so a sandbox account cannot run batches. See Batches.
• Human review resumes inline. POST /executions/{id}/review_decisions on a test-mode execution runs the chosen branch synchronously and answers 200 with the final state; live-mode decisions enqueue the resume and answer 202.
• Webhooks still fire. execution.* and adverse_action.* events are delivered for test runs too, so you can build your handler end to end. execution.* payloads carry "execution_mode": "test"; adverse_action.* payloads do not carry it — join on workflow_execution_id and read input_context.execution_mode from GET /executions/{id}.

What does live mode require?

Two things, checked on every live request:

1. An approved account. Approval is granted by CRS after the activation form at /activate is reviewed. Until then every execution_mode: live request is refused with 403 live_mode_forbidden.
2. An active cascade. Live triggers on a draft return 409 workflow_inactive.

Live runs pull real consumer reports and are billable. On the CRS sandbox host, a live-mode run from an approved account with a normal key (not a docs key) also matches the registered test subjects: when the applicant matches a registry entry, the authored bureau response is replayed instead of a vendor pull, and a miss reaches the billable vendor — see Test identities. You need a permissible purpose under the FCRA for every live pull — see FCRA permissible purpose.

Which requests are gated?

Everything else (reading, single test-mode triggers, webhooks, templates, deleting) works the same in both modes.

How do I tell which mode a run used?

• The trigger and batch responses echo execution_mode.
• GET /executions/{id} includes it in input_context.execution_mode.
• Webhook payloads for execution.* events carry execution_mode; adverse_action.* payloads do not, so resolve the execution first.

Filter your own records on it before acting on a decision: a test-mode approval is a synthetic approval.

Keys minted from the docs

When you are signed in, the key injected into these pages is a short-lived, sandbox-only token: it expires after an hour or when you sign out, and is refused for any live request even on an approved account. On an approved account the refusal says so: live requests answer 403 live_mode_forbidden with "Docs keys are sandbox-only, so they never run live", activation answers 403 activation_forbidden, and POST /workflows creates a draft with a note that names the docs key. Mint a real key at /api-keys for your integration, or activate the cascade in the app.

Going live checklist

• Account approved (the sandbox banner in the app disappears)
• Cascade active (active: true), tested end to end in test mode
• Integration key holds only the scopes you need
• Idempotency-Key derived from a stable business id
• Webhook signature verification rejects stale t and wrong v1
• Your side records execution_mode from the trigger response or GET /executions/{id} and never treats a test decision as real