<!-- Generated by scripts/gen-developer-docs.ts from src/developers/content/recruit/test-mode.md — do not edit. -->

# Test mode

> Test keys run the whole API against realistic fake roles, invites and reports: no email, no text, no credits, and never a live object.

## Test keys

Owners create a test key in **Settings › Integrations › API keys** by choosing **Mode: Test** (offered while test mode
is available for your workspace). Test keys start with `r100x_test_` and see only test objects.

## What a test key does

- `POST /api/v1/roles` makes a test role (`role_test_…`) with a synthetic title read from your request; its guide is
  approved by itself about 10 seconds later and `role.ready` goes to your test webhooks.
- `POST /api/v1/roles/{roleId}/invites` makes test invites (`inv_test_…`) with the same request rules as live; nobody
  is emailed. With `"delivery": "return_link"` each row's `screen_url` opens a test page, `/test/screen/{token}`.
- The test page has **Simulate completion** (sends `screen.completed`, then `report.ready` with a sample report) and
  **Simulate a failed report** (`screen.completed`, then `report.failed`). The page shows where each event went.
- Reports, invite reads, the new-link and cancel routes, and the candidate-care stats answer from the test objects.
- `POST /api/v1/hooks/{hookId}/test` pings a test endpoint through the test sender, and so does **Send test event** in
  Settings › Integrations. Test events are sent once and aren't logged, so they can't be replayed.

Every test answer carries `"livemode": false`. Test ids (`role_test_…`, `inv_test_…`, `rep_test_…`) are accepted
wherever the API takes an id; a test role has no `dashboard_url`, and a test report's `url` is its API read.

## Test events and payload versions

Each test endpoint gets the payload version it was created with, as live endpoints do. A `2026-11-01` endpoint gets
the `2026-11-01` body with `"livemode": false` and the `role.*` events. A `2026-09-01` endpoint gets the frozen
`2026-09-01` body, which has no `livemode` field, and no `role.*` events; the event id's `evt_test_` prefix marks it as a
test event.

A workspace can have up to 10 test endpoints, apart from its 10 live ones.

## The two modes never meet

A live key that names a test object, or a test key that names a live object, gets `403 TEST_MODE_ONLY`. Live events
never reach an endpoint created with a test key, and test events never reach a live endpoint. Test objects are deleted
after 30 days.
