Build on the records API

# Paste the key from the sandbox key page once per shell
export TAVRN_API_KEY="tavrn_sk_test_…"

# Create the case the records belong to
curl -X POST https://sandbox.tavrn.ai/v2/cases \
  -H "Authorization: Bearer $TAVRN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Doe v. Example Motors", "client_name": "Jane Doe",
        "client_date_of_birth": "1980-01-15" }'

# 201 Created
{
  "id": "15e6af1b…",
  "case_number": "SBX-000001",
  "title": "Doe v. Example Motors",
  "client_name": "Jane Doe",
  "client_date_of_birth": "1980-01-15",
  "case_category": "other",
  "status": "active",
  "created_at": "2026-10-15T01:50:42.292Z",
  "updated_at": "2026-10-15T01:50:42.292Z"
}

# Upload the (synthetic) signed authorization: presigned URL, then PUT the PDF
curl -X POST https://sandbox.tavrn.ai/v2/cases/{case_id}/sign-upload \
  -H "Authorization: Bearer $TAVRN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "file_name": "auth_form.pdf", "file_type": "application/pdf", "purpose": "retrieval_attachment" }'
# 201 → { "upload_id": "b97c904a…", "upload_url": "https://…", "expires_at": "…" }
curl -X PUT "{upload_url}" -H "Content-Type: application/pdf" --upload-file auth_form.pdf

# Request records from a sandbox facility (facility_id, or an inline facility with name + address);
# the scenario header forces the outcome
curl -X POST https://sandbox.tavrn.ai/v2/cases/{case_id}/retrieval-requests \
  -H "Authorization: Bearer $TAVRN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Tavrn-Sandbox-Scenario: complete" \
  -d '{
    "patient": { "name": "Jane Doe", "date_of_birth": "1980-01-15" },
    "facility_id": "{facility_id from GET /v2/facilities?q=General}",
    "requested_records": [ { "type": "medical_records" }, { "type": "billings" } ],
    "auth_form": { "upload_id": "{upload_id}", "file_name": "auth_form.pdf" }
  }'

# 201 Created
{
  "id": "c284b9fb…",
  "order_number": "T-SBX-00001",
  "case_id": "15e6af1b…",
  "status": "received",
  "created_at": "2026-10-15T01:51:31.464Z",
  "updated_at": "2026-10-15T01:51:31.464Z",
  "requestor_id": "43b3cb6d…"
}

# Poll the request (or register a webhook and wait for the delivery)
curl https://sandbox.tavrn.ai/v2/retrieval-requests/{id} \
  -H "Authorization: Bearer $TAVRN_API_KEY"

# 200 OK — stages advance on their own; "complete" ends at status "completed"
{
  "id": "c284b9fb…",
  "order_number": "T-SBX-00001",
  "case_id": "15e6af1b…",
  "status": "received",
  "stage": "submitted",
  "stage_label": "Submitted",
  "timeline": [
    { "stage": "submitted",        "state": "current", "occurred_at": "2026-10-15T01:51:31.464Z" },
    { "stage": "locating_contact", "state": "pending" },
    { "stage": "request_sent",     "state": "pending" }
  ],
  "sandbox": { "scenario": "complete" }
}

# Webhook: one signed POST per status change
curl -X POST https://sandbox.tavrn.ai/v2/webhooks \
  -H "Authorization: Bearer $TAVRN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/tavrn", "events": ["retrieval_request.status_changed"] }'

Base URL https://sandbox.tavrn.ai/v2 · tavrn_sk_test_ keys only · same endpoints, stages and webhook signatures as production · API reference · OpenAPI. Scenarios: complete, action_required_payment, contact_missing, request_issue, no_records, stalled (append ,slow for realistic timing).