Get started

Sandbox scenarios

Sandbox scenarios are stable examples you can run while building your Collate integration. Each scenario creates a predictable authorization lifecycle so you can test your code before sending live prior-authorization traffic.

Scenarios use the same public Prior Auth API resources as production: Authorization.status, Authorization.nextAction, requirements, submissions, outcomes, files, final approval, and manual handoffs.

Scenarios do not call live payer portals, use real payer credentials, or expose internal Collate test endpoints. They are available only in sandbox:

https://api.sandbox.trycollate.ai

Get the scenario catalog

Fetch the catalog to see the scenarios available to your organization:

$curl -sS "$COLLATE_BASE_URL/v1/sandbox/scenarios" \
>  -H "Authorization: Bearer $COLLATE_API_KEY" \
>  | tee sandbox-scenarios.json

Each scenario includes:

  • a stable id
  • production-shaped create.providerNpi, create.request, create.policy, and create.answers
  • the requirements, documents, or confirmations the scenario may ask for
  • the statuses, next actions, and outcomes your client should expect
  • a suggested timeout for automated tests

Retrieve one scenario when you want the create data for a specific example:

$curl -sS "$COLLATE_BASE_URL/v1/sandbox/scenarios/quickstart_receipt" \
>  -H "Authorization: Bearer $COLLATE_API_KEY" \
>  | tee scenario.json

Create from a scenario

Use the create fields returned by the scenario:

$jq -n --slurpfile scenario scenario.json \
>  '{
>    providerNpi: $scenario[0].create.providerNpi,
>    request: $scenario[0].create.request,
>    policy: $scenario[0].create.policy,
>    answers: $scenario[0].create.answers,
>    metadata: { externalCaseId: "sandbox-quickstart" }
>  }' > create.json

The request body is the same shape you use in production. In sandbox, the member information inside create.answers chooses the scenario. You do not need to send a scenario field or custom scenario header.

Available scenarios

ScenarioUse it to test
quickstart_receiptA basic create, requirements, confirm, and waiting_on_payer flow.
approvedA completed authorization with an approved outcome.
deniedA completed authorization with a denied outcome.
not_requiredA completed authorization where prior authorization is not required.
document_requiredUploading and attaching a required supporting document.
final_approvalReviewing and approving a final submission before Collate submits it.
payer_follow_upHandling payer follow-up requirements after submission.
manual_handoff_requiredCompleting a payer interaction outside Collate and reporting it back.

Run a scenario

After creating the authorization, drive your client from the returned authorization state:

  1. Read status and nextAction.
  2. If the API asks for requirements, patch answers or attach the requested files.
  3. If the API asks for confirmation, call /confirm.
  4. If the API asks for manual completion, follow the manual-handoff response.
  5. Poll the authorization until it reaches the status or outcome described by the scenario.

Your integration should follow the API response at each step. Different scenarios intentionally ask for different actions, so do not assume every authorization follows the same sequence.