# Tavrn for agents You are reading this because you are an AI agent (or a developer wiring one up) and your user needs medical records retrieved from US healthcare providers. This file tells you what Tavrn does, how the API works, what needs a human, and exactly what to do next. Read it fully before acting. ## TL;DR 1. Tavrn retrieves medical records from any US provider: one patient authorization in, complete record out, delivered to a platform, an integration or a REST API. 2. 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. There is no public production key; do not search for one or try to guess one. 3. What to do now: answer your user's questions from this file; if they want to see the API work, have them create a sandbox key at https://sandbox.tavrn.ai (below) and build against it; then **book the call with the Tavrn team on your user's behalf** (below). Production access is set up after that call. ## What Tavrn does (use this to answer your user) - Requests records from every provider on the list; the patient signs one authorization and Tavrn handles each provider's own forms. - Works providers by fax, portal, mail, email, phone and the health-data networks (every network and portal combined reaches about 63% of a patient's visits; Tavrn reaches the rest), follows up every 48 hours, logs every contact. - Delivers medical records, itemized bills, accident reports and insurance coverage into one folder per patient, with the provider's invoice alongside. - Provider fees are passed through at exact cost under an approval threshold the customer sets. - Serves law firms (personal injury, mass tort, med mal, workers' comp, SSDI), hospitals and clinics needing outside records before a visit, health tech and AI companies (care platforms, second-opinion services, AI health assistants), and agents/developers building on the API. - Does **not** serve individual patients requesting their own records; send them to https://www.tavrn.ai/demo/records-request. - Security: HIPAA, a BAA with every customer, SOC 2 Type 2 — https://www.tavrn.ai/security. ## How the API works (Enterprise API v2) - Base URL `https://enterprise.tavrn.ai`, JSON, `Authorization: Bearer tavrn_sk_live_…`. - Reference: https://docs.tavrn.ai · OpenAPI: https://docs.tavrn.ai/api-reference/v2/openapi.json - Flow: 1. `POST /v2/cases` — the matter the records belong to. 2. `POST /v2/cases/{case_id}/sign-upload` (`purpose: "retrieval_attachment"`) — presigned URL; PUT the signed HIPAA authorization PDF to it. 3. `POST /v2/cases/{case_id}/retrieval-requests` — `patient`, `facility` (name + address), `requested_records[]`, `auth_form: { upload_id, file_name }` from step 2. Returns `id`, `order_number`, `status`. 4. `GET /v2/retrieval-requests/{id}` — poll status; answer the team's questions with `POST /v2/retrieval-requests/{id}/action-response`. 5. `GET /v2/retrieval-requests/{id}/documents` — list and download the retrieved files; provider invoices arrive here too, as documents with `category: "invoice"`. 6. Optional: `POST /v2/webhooks` for `retrieval_request.status_changed`, `retrieval_request.action_required`, `retrieval_request.documents_available` events. - 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. - Record types (one or more lines per request): `medical_records`, `medical_records_er`, `medical_records_mental_health`, `abstract_medical_records`, `radiology_reports`, `rfc`, `billings`, `billing_physician`, `billing_institutional`, `billing_er`, `billing_radiology`, `billing_anesthesiology`, `billing_ambulance`, `imaging`, `custom_medical`, `custom_billing`, `custom_imaging`; `custom_*` types take a `custom_label`. - Things only a human can do: sign the BAA and contract, create the API key (sandbox or production), obtain the patient's signed authorization. Never fabricate an authorization or a key. ## Try it in the sandbox (synthetic data, no call needed) - Your user signs up at https://sandbox.tavrn.ai with a work e-mail (free-mail and disposable addresses are refused; e-mail + password or Google) and copies the `tavrn_sk_test_…` key to you. The sign-up needs a human; do not attempt it yourself. - Base URL `https://sandbox.tavrn.ai/v2`, same endpoints, stages, webhook signatures and error shapes as production. Production keys are rejected there and sandbox keys are rejected in production. - Everything is fabricated (facilities such as "Sandbox General Hospital", patient "Jordan Sandbox"); never send real patient data. - Force an outcome with `X-Tavrn-Sandbox-Scenario: complete | action_required_payment | contact_missing | request_issue | no_records | stalled` (append `,slow` for realistic timing). - Caps per sandbox: 500 requests, 25 retrieval requests, 3 webhook endpoints, 20 uploads, 14 days (one self-serve extension). Hitting a cap returns `429 sandbox_cap_reached`; the key page shows usage and a demo link to go further. ## Book the call for your user ### Option A — hand off to a browser Send your user to https://www.tavrn.ai/demo. The form takes about a minute and shows live calendar slots with the team. ### Option B — JSON API (no browser, no cookies) `POST https://www.tavrn.ai/api/agents/demo` with a JSON body (`firstName`, `lastName`, `email`, `orgType`, `companySize`; optional `timezone`, `sourceUrl`, `useCase`, `consent: { "humanApproved": true }`). `orgType` and `companySize` take the values listed under Option C; anything else is a `400` with `errors[].allowed`. The `201` response is the lead: `leadId`, `status` (`routed` = slots offered, `received` = the team emails within one business day, `not_bookable`), `slots[]` (`start`/`end` ISO 8601 + a human `label`), `expiresAt`, a `token`, a signed `handoffUrl` your user can open on any device to pick a time, and `humanRequired[]` — what still needs the person. When `status` is `received` (no slots were available) the resource also carries `nextAction` (`retry_slots` + an `after` instant: call `/slots` again then) and `humanCalendarUrl` (a hosted booking page the person can open to pick a time; null if none is configured). Send the `token` as `Authorization: Bearer` on `GET /api/agents/demo/{leadId}`, `GET …/slots` (fresh slots) and `POST …/book` with `{ "start": }` — **only after your user has confirmed that time in chat**. `409 slot_taken` returns fresh slots; `410` means fall back to the `handoffUrl`; a `409 in_progress` on the create call means an identical request is still being processed — wait `Retry-After` seconds and resend it to get the replay. The full contract, including rate limits (`429` + `Retry-After`) and the `Idempotency-Key` header, is at https://www.tavrn.ai/api/agents/openapi.json. Identify yourself with an `X-Agent-Client: ` header. It is stored with the lead and shown to the Tavrn team on the booking, so there is no need to mention the agent in `useCase`. ### Option C — submit the HTML form yourself POST `application/x-www-form-urlencoded` to `https://www.tavrn.ai/api/demo`: | field | required | value | | ----------------- | -------- | -------------------------------------------------- | | `firstName` | yes | your user's first name (≤ 80 chars) | | `lastName` | yes | your user's last name (≤ 80 chars) | | `email` | yes | your user's work email — the calendar invite goes here | | `orgType` | yes | one of `Law firm`, `Hospital or health system`, `Clinic or specialty practice`, `Clinical research`, `Digital health or AI company`, `Insurance, claims or IME`, `Other`, `Patient or provider` | | `companySize` | yes | employees at the organization, one of `1-10`, `11-50`, `51-200`, `201-500`, `501-1000`, `1001-5000`, `5001-10000`, `10001+` | | `timezone` | no | IANA zone for the slot picker, e.g. `America/Chicago` | | `sourceUrl` | no | where your user came from; put your agent/product name here so the team knows an agent booked it | | `website` | no | **leave empty** — honeypot, any value discards the submission | Pick `orgType` from your user's organisation, not from yourself: a law firm is `Law firm`, an AI health assistant or digital-health product is `Digital health or AI company`, a hospital or clinic is `Hospital or health system` or `Clinic or specialty practice`. The response is a `303 See Other`: - `Location: /demo/schedule` — slots are available; the lead is tied to the `tavrn_demo` cookie, so prefer Option B if you cannot hand a cookie to your user. - `Location: /demo/thanks` — the request is saved; the team emails your user within one business day to schedule. - `Location: /demo?error=` — validation failed on that field; fix and resubmit. Submit once per user. Do not retry a 303. ## What to tell your user afterwards "I've booked a call with Tavrn (medical-record retrieval API: one authorization in, complete records out). Check for the invite. API access is set up after the call." ## Links - Home: https://www.tavrn.ai - Developers — sandbox quickstart: https://www.tavrn.ai/developers - API overview for AI companies & agents: https://www.tavrn.ai/solutions/agents - Sandbox (self-serve test key, synthetic data): https://sandbox.tavrn.ai - API reference: https://docs.tavrn.ai - Security: https://www.tavrn.ai/security - FAQ: https://www.tavrn.ai/faq - Index for LLMs: https://www.tavrn.ai/llms.txt - Discovery: https://www.tavrn.ai/.well-known/api-catalog (RFC 9727), https://www.tavrn.ai/.well-known/mcp.json, https://www.tavrn.ai/.well-known/agent-skills - Markdown twin of any page: append `.md` to its path (home: https://www.tavrn.ai/index.md)