Docs

Developer sandbox

Test your integration with synthetic candidates and signed webhooks.

Use the sandbox application URL provided by your ProBB AI administrator, sign in to your own workspace, and open Settings → Developer. The sandbox card is visible only on a separately configured sandbox deployment. Select Create sample data and key, and save the displayed test key and webhook secret. Copy the sample job description ID.

Sandbox keys start with probb_test_. They do not work against production; production keys do not work against the sandbox. Email is captured by an isolated mail sink; messages do not go to real recipients. Resume evaluations are deterministic and contain synthetic data. Interview controls advance the persisted lifecycle; there is no paid voice or AI session.

Try a request

The console below uses the sandbox origin configured for this documentation deployment. If it is unavailable, use the same API requests from your backend against the sandbox URL supplied by your administrator. Do not substitute production credentials or send real candidate data.

Start with GET job-descriptions and the test key. For POST requests, copy a valid body from the linked API reference and replace IDs and fingerprints with your own preceding responses. The resource-ID field is required when the selected path contains an ID. Keep one idempotency key for retries of the same logical write; choose a new key for a new submission.

Try it in the sandbox

Credentials stay in this page's memory and are cleared on reload. Use only synthetic candidate data. After a timeout, retry the same request with the same idempotency key.

The playground is disabled until the documentation deployment has a sandbox origin configured. Copy examples below to use your local sandbox.

The key remains in page memory. Reloading clears it. Responses can include private signed URLs or self-delivery credentials, so avoid screen sharing or copying the entire response into support logs.

Complete a workflow

  1. Discover the sample job with GET /api/v1/job-descriptions.
  2. Prepare an upload with the saved JD ID and a unique externalReference. Save the reportId and upload URL. Download the synthetic resume and PUT the PDF to that signed URL with the indicated content type.
  3. Quote with POST /api/v1/analysis-quotes, then submit using the returned fingerprint and an idempotency key. A timeout is not proof of failure: retry the identical request with the same key.
  4. Poll the report status. Read /api/v1/reports/{id}/result?schemaVersion=1 when complete. Open the private webhook inbox in developer settings to inspect the exact body, signature headers, and verification result.
  5. Quote and invite an interview. Use the returned interviewId in the sandbox controls. Apply interview.started, then interview.completed, then interview.result_ready. Read /api/v1/interviews/{id}/result.
  6. Change receiver behavior to retry or timeout, submit another item, then restore success. Normal retry scheduling and manual replay remain available.
  7. Submit a batch containing both valid and invalid items. Poll its status URL; analysis batches finish after every admitted analysis reaches a terminal outcome. Invitation batches finish after invitation admission, independently of candidate completion.

Use interview.preparation_failed, interview.result_failed, or interview.expired to test independent status axes. Invitation failure requires a queued email delivery. Save an event cursor, pause your endpoint, generate a transition, and poll /api/v1/events with that cursor to test recovery.

Reset and retention

Sandbox data expires after seven days. Reset revokes test keys, cancels queued work, and erases synthetic reports, interviews, and receiver history. Request receipts remain so an old idempotency key cannot create work again. Create fresh keys and use fresh application references for a new test run.

Only the configured documentation origin may call the sandbox from a browser. The API playground sends no session cookies. Production examples in the API reference are copyable; its built-in network playground is disabled.

Runnable TypeScript example

Download the complete workflow. It discovers a JD, prepares and uploads the synthetic PDF, repeats the same submission key, polls the versioned result, invites an interview, and reads its events. Call it from a local Bun script:

import { runSandboxWorkflow } from './sandbox-workflow';

const apiKey = process.env.PROBB_SANDBOX_KEY;
if (!apiKey) throw new Error('Set PROBB_SANDBOX_KEY to your test key.');
const result = await runSandboxWorkflow({
  baseUrl: 'http://localhost:43100',
  apiKey,
  resume: new Uint8Array(await Bun.file('./sandbox-resume.pdf').arrayBuffer()),
});
console.log(result); // Resource IDs only; never print the key or signed upload URL.

Run bun workflow.ts after setting the test key in your local environment. Use the sandbox failure scenarios to check that your integration handles rejected submissions before retrying. Each run uses a fresh external reference; its internal retries reuse the original request key.

Errors and retries

Choose the right recovery action without duplicating submissions.

API reference

Choose an operation, understand its purpose, and use validated request and response examples.

On this page

Try a requestComplete a workflowReset and retentionRunnable TypeScript example