Get started

Quickstart

This tutorial creates a deterministic sandbox authorization with quickstart_receipt, patches starter answers, attaches a supporting PDF, and confirms the current action when the API asks for confirmation.

The REST API is the canonical integration surface. The SDKs are in beta and are covered separately in the SDK guides. You finish with an Authorization ID your system can poll until the case needs another action, waits on the payer, completes, or is canceled.

Before you start

You need:

  • a sandbox API key
  • curl and jq
$export COLLATE_API_KEY="your-sandbox-api-key"
$export COLLATE_BASE_URL="https://api.sandbox.trycollate.ai"
$export SANDBOX_SCENARIO_ID="quickstart_receipt"
1

Fetch the scenario

Load the scenario from the public sandbox catalog. The catalog is the source of truth for the provider NPI, request tuple, policy, expected observations, and timeout.

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

Create an authorization

Create one authorization for one payer submission. Use a fresh idempotency key for each new create request. The create body is production-shaped; the sandbox scenario includes starter answers for this example.

$jq -n --slurpfile scenario scenario.json \
>  --arg externalCaseId "quickstart-demo" \
>  '{
>    providerNpi: $scenario[0].create.providerNpi,
>    request: $scenario[0].create.request,
>    policy: $scenario[0].create.policy,
>    answers: $scenario[0].create.answers,
>    metadata: { externalCaseId: $externalCaseId }
>  }' > create-authorization.json
$curl -sS -X POST "$COLLATE_BASE_URL/v1/prior-authorizations" \
>  -H "Authorization: Bearer $COLLATE_API_KEY" \
>  -H "Idempotency-Key: $(uuidgen)" \
>  -H "Content-Type: application/json" \
>  -d @create-authorization.json \
>  | tee authorization.json

Save the returned ID and version. You will use version as If-Match on mutable authorization writes.

$export AUTH_ID="$(jq -r '.id' authorization.json)"
$export AUTH_VERSION="$(jq -r '.version' authorization.json)"
3

Patch starter answers

If the authorization asks for requirements, patch the answers you already have. Omitted fields are left unchanged. This quickstart reuses the scenario answers so the authorization stays aligned with the selected scenario.

$jq '{ answers: .create.answers }' scenario.json \
>  | curl -sS -X PATCH "$COLLATE_BASE_URL/v1/prior-authorizations/$AUTH_ID/answers" \
>  -H "Authorization: Bearer $COLLATE_API_KEY" \
>  -H "If-Match: \"$AUTH_VERSION\"" \
>  -H "Content-Type: application/json" \
>  -d @- \
>  | tee authorization.json
$
$export AUTH_VERSION="$(jq -r '.version' authorization.json)"

In a real integration, use the returned questionnaire as the source of valid linkIds and answer shapes. The sandbox catalog explains what each scenario may ask for; it does not replace the authorization questionnaire.

4

Attach a PDF

Upload a PDF as a File, complete the upload, then link it as an attachment.

$curl -sS -X POST "$COLLATE_BASE_URL/v1/files" \
>  -H "Authorization: Bearer $COLLATE_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "fileName": "clinical-note.pdf",
>    "contentType": "application/pdf",
>    "purpose": "authorization_attachment"
>  }' | tee file.json
$
$export FILE_ID="$(jq -r '.file.id' file.json)"
$export UPLOAD_URL="$(jq -r '.upload.url' file.json)"
$export UPLOAD_METHOD="$(jq -r '.upload.method' file.json)"
$
$UPLOAD_HEADERS=()
$while IFS= read -r header; do
$  UPLOAD_HEADERS+=("-H" "$header")
$done < <(jq -r '.upload.headers // {} | to_entries[] | "\(.key): \(.value)"' file.json)
$
$curl -sS -X "$UPLOAD_METHOD" "$UPLOAD_URL" \
>  "${UPLOAD_HEADERS[@]}" \
>  --data-binary @clinical-note.pdf
$
$curl -sS -X POST "$COLLATE_BASE_URL/v1/files/$FILE_ID/complete" \
>  -H "Authorization: Bearer $COLLATE_API_KEY" \
>  | tee file-complete.json
$
$curl -sS -X POST "$COLLATE_BASE_URL/v1/prior-authorizations/$AUTH_ID/attachments" \
>  -H "Authorization: Bearer $COLLATE_API_KEY" \
>  -H "If-Match: \"$AUTH_VERSION\"" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "fileId": "'"$FILE_ID"'",
>    "documentTypes": ["clinical_notes"]
>  }' | tee authorization.json
$
$export AUTH_VERSION="$(jq -r '.version' authorization.json)"

See Attaching files for production upload handling.

5

Confirm when the API asks

Confirm only when nextAction.type is continue_authorization or approve_submission.

$export NEXT_ACTION="$(jq -r '.nextAction.type // empty' authorization.json)"
$
$if [ "$NEXT_ACTION" = "continue_authorization" ]; then
$  curl -sS -X POST "$COLLATE_BASE_URL/v1/prior-authorizations/$AUTH_ID/confirm" \
>    -H "Authorization: Bearer $COLLATE_API_KEY" \
>    -H "If-Match: \"$AUTH_VERSION\"" \
>    -H "Content-Type: application/json" \
>    -d '{}' | tee authorization.json
$fi
$
$if [ "$NEXT_ACTION" = "approve_submission" ]; then
$  export REVIEW_ID="$(jq -r '.submission.reviewSnapshot.id' authorization.json)"
$
$  curl -sS -X POST "$COLLATE_BASE_URL/v1/prior-authorizations/$AUTH_ID/confirm" \
>    -H "Authorization: Bearer $COLLATE_API_KEY" \
>    -H "If-Match: \"$AUTH_VERSION\"" \
>    -H "Content-Type: application/json" \
>    -d '{ "acceptedReviewSnapshotId": "'"$REVIEW_ID"'" }' \
>    | tee authorization.json
$fi

Do not call /confirm for resolve_requirements. Patch answers or attach required documents instead.

6

Poll the authorization

Read the latest authorization before each decision.

$curl -sS "$COLLATE_BASE_URL/v1/prior-authorizations/$AUTH_ID" \
>  -H "Authorization: Bearer $COLLATE_API_KEY" \
>  | tee authorization.json

Use this quick reference while building the loop:

Latest fieldWhat to do
status = "requires_action"Resolve the current nextAction.type.
status = "processing"Poll again after a short delay.
status = "waiting_on_payer"Poll less frequently for payer follow-up or outcome.
status = "completed"Read outcome and submission.decision.
status = "canceled"Stop local work.

Next Steps