Skip to main content
A test key lets you build against the API without spending anything. Jobs made with it run through the real pipeline with every paid service switched off, are kept apart from your live jobs, and are not metered.

​
Get a test key

Create one with mode: test (needs keys:manage). The key is returned once, as for any key.
  • Test keys start pk_test_, in every environment. A live key starts pk_live_ in production; elsewhere every key starts pk_test_, so read mode (on the key, from GET /v1/api-keys) rather than the prefix.
  • A platform that provisions tenants can ask for one: issue_api_key: true with api_key_mode: "test".
  • Rotating a key keeps its mode.
  • A test key holds job scopes only: jobs:write, jobs:read, jobs:delete and underwriting:write. It cannot manage keys, webhooks, mailboxes, integrations or settings, so a leaked one reaches no live job and cannot mint a live key.
Use it exactly like a live key: POST /v1/parse, GET /v1/jobs/{job_id}, corrections, file downloads.

​
What is off

A test job is read as a deployment without the paid services would read it, and says so: test_mode: true on the job (GET /v1/jobs/{job_id}) and on its result. So a test result is real but unlabelled: use it to check your integration (upload, webhook, status handling, mapping the response fields), not to judge categories or positions. A test job costs nothing and its usage.cost_usd is 0.

​
Test and live are separate

Like Stripe’s two modes, a key sees only the jobs of its own mode:
  • GET /v1/jobs lists test jobs for a test key and live jobs for a live key.
  • A job of the other mode is 404 on every /v1/jobs/{job_id} route (result, files, corrections, erasure). An Idempotency-Key used in one mode cannot be reused in the other (409).
  • DELETE /v1/jobs?end_user_id= erases the jobs of the key’s own mode.
  • Test jobs are not metered: they do not appear in GET /v1/usage, the quality report, or toward a monthly budget, and a spent monthly budget does not stop them.

​
Webhooks

Your webhook endpoints belong to the tenant, not to a mode, so they receive test jobs’ events too. Check payload.livemode: it is false for a test job and true for a live one.
A test job’s event is not sent to your CRM integrations, so test data never reaches your real CRM.

​
Limits still apply

A test key is rate limited like any key, and max_active_jobs caps the queued and running test jobs (counted apart from your live jobs, so a test run never holds up production).