---
title: "Build on the records API"
description: "One REST contract for medical record retrieval from any US provider: create a case, attach the signed authorization, request records, get a webhook on every status change. Start on synthetic data today with a self-serve sandbox key."
canonical: https://www.tavrn.ai/developers
updated: 2026-10-16
---

# Build on the records API

One REST contract for medical record retrieval from any US provider: create a case, attach the signed authorization, request records, get a webhook on every status change. Start on synthetic data today with a self-serve sandbox key.

[Get a sandbox key](https://sandbox.tavrn.ai) · [API reference](https://docs.tavrn.ai/api-reference/v2)

## First request in four steps.

Test keys are self-serve: sign up at sandbox.tavrn.ai with a work email and get a tavrn_sk_test_ key for synthetic data in a minute. Production keys are issued to customer organizations in the Tavrn dashboard after a 30-minute call.

1. **Sign up** — Create a sandbox account at sandbox.tavrn.ai with a work email. No call, no contract, no production data.
2. **Get a key** — Copy your tavrn_sk_test_ key from the key page and export it as TAVRN_API_KEY; every request to sandbox.tavrn.ai/v2 sends it as Authorization: Bearer.
3. **Create a case, request records** — POST /v2/cases, upload a synthetic authorization through sign-upload, then POST a retrieval request with X-Tavrn-Sandbox-Scenario: complete to force the happy path.
4. **Watch it complete** — Register a webhook and receive retrieval_request.status_changed, or poll GET /v2/retrieval-requests/{id} until status is completed.

## Sandbox quickstart

### 1 · Create a case

```
# 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"
}
```

### 2 · Request records

```
# 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…"
}
```

### 3 · Outcome

```
# 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).

## Four resources. Plain REST.

Every record request lives under a case. Statuses are coarse and public; documents are downloaded with the same key.

- `POST /v2/cases` — A case to attach retrieval requests and documents to
- `POST /v2/cases/{case_id}/sign-upload` — Presigned URL for the authorization PDF or attachments
- `POST /v2/cases/{case_id}/retrieval-requests` — id, order_number, status
- `GET /v2/retrieval-requests/{id}` — Status, timeline, action requests
- `POST /v2/retrieval-requests/{id}/action-response` — Answer a question from the team
- `GET /v2/retrieval-requests/{id}/documents` — Retrieved files, each with a download URL
- `POST /v2/webhooks` — Signed deliveries on every status change

## Request status

- **received** — Accepted; the team is validating the authorization and provider.
- **processing** — Being worked with the provider; follow-ups every 48 hours.
- **action_required** — Tavrn needs something from you — answer via the action-response endpoint.
- **completed** — Terminal. Documents are ready to list and download.
- **cancelled** — Terminal. Cancelled by you or because the provider cannot fulfil it.

## Three events, signed on every delivery.

Register an HTTPS endpoint with POST /v2/webhooks and pick the events you need. Each delivery is signed so you can verify it came from Tavrn; retries follow the schedule in the reference.

- `retrieval_request.status_changed` — Any status or stage change on a retrieval request.
- `retrieval_request.action_required` — The team needs something from you; answer via action-response.
- `retrieval_request.documents_available` — Retrieved files are ready to list and download.

## Same contract. Two things only a human does.

Nothing in your integration changes between sandbox and production except the base URL and the key.

### Sign the BAA

Tavrn handles protected health information under HIPAA. A Business Associate Agreement is reviewed with your team on a 30-minute call before any live request.

### Get a live key

Production keys (tavrn_sk_live_) are created by an admin of your organization in the Tavrn dashboard; they are never self-serve and never work against the sandbox.

### Switch the base URL

Point the same code at enterprise.tavrn.ai/v2, drop the scenario header, and send real signed authorizations. Endpoints, statuses, webhook payloads and error shapes are identical.

## Controls for sensitive medical records

Protected health information, handled under HIPAA and audited for SOC 2.

- [HIPAA compliance](https://www.tavrn.ai/security)
- [SOC 2](https://www.tavrn.ai/security)
- [BAA](https://www.tavrn.ai/security)
- [SSO](https://www.tavrn.ai/security)
- [Audit trail](https://www.tavrn.ai/security)

## Building with an AI agent?

Everything on this page is also published as plain text for agents and crawlers. Point your agent at agents.md; it explains what Tavrn does, what needs a human, and how to book the call on your behalf.

- [/agents.md](https://www.tavrn.ai/agents.md) — instructions for an agent acting for a user
- [/llms.txt](https://www.tavrn.ai/llms.txt) — index of this site for LLMs
- [openapi.json](https://docs.tavrn.ai/api-reference/v2/openapi.json) — Enterprise API v2 specification
- [sandbox.tavrn.ai](https://sandbox.tavrn.ai) — self-serve test key, synthetic data only
- [API reference](https://docs.tavrn.ai) — guides: retrieval, uploads, webhooks, errors

## Ready for real records?

Book 30 minutes to cover your use case, volumes and the BAA. Production access is set up right after.

[Book a demo](https://www.tavrn.ai/demo)