Skip to content

Developers

Medical record retrieval API

The Tavrn Enterprise API v2 is a REST API for medical record retrieval from any US provider: create a case, attach the patient’s signed authorization, open one retrieval request per provider, and receive a signed webhook on every status change until the documents are ready to download. Bearer keys, idempotent POSTs and a self-serve sandbox; every section links to its page in the reference.

Get a sandbox keyAPI reference

At a glance

One REST contract, two hosts

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

TopicEnterprise API v2Reference
Production base URLhttps://enterprise.tavrn.ai/v2Authentication guide
Sandbox base URLhttps://sandbox.tavrn.ai/v2, tavrn_sk_test_ keys onlySandbox guide
AuthenticationAuthorization: Bearer <key>; live keys start with tavrn_sk_live_, scoped per resourceAuthentication guide
VersioningDated versions pinned with the Tavrn-Version header; additive changes ship to every versionVersioning guide
IdempotencyIdempotency-Key header on any POST; the first outcome is replayed for 24 hoursIdempotency guide
PaginationCursor-based; limit defaults to 20, maximum 100API reference
ErrorsOne JSON envelope with error.code, error.message and error.request_id; every response carries a Request-Id headerErrors guide
WebhooksSigned HTTPS deliveries on status changes, action requests and documents availableWebhooks guide

Endpoints

Cases, retrieval requests, documents, webhooks

Every record request lives under a case. A retrieval request is one provider with its own status, timeline and documents; facilities, requestors and events are the supporting resources.

ResourceMethodPathReturns
CasesPOST/v2/casesA case to attach retrieval requests and documents to
CasesPOST/v2/cases/{case_id}/sign-uploadPresigned URL for the authorization PDF or attachments
Retrieval requestsPOST/v2/cases/{case_id}/retrieval-requestsid, order_number, status
Retrieval requestsGET/v2/retrieval-requests/{id}Status, timeline, action requests
Retrieval requestsPOST/v2/retrieval-requests/{id}/action-responseAnswer a question from the team
DocumentsGET/v2/retrieval-requests/{id}/documentsRetrieved files, each with a download URL
WebhooksPOST/v2/webhooksSigned 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.
Full endpoint reference

Authentication

Bearer keys, scoped and environment-bound

Send the key as Authorization: Bearer on every request. Keys are shown once at creation and can be rotated.

Two prefixes, two hosts
tavrn_sk_test_ keys work only against sandbox.tavrn.ai, tavrn_sk_live_ keys only against enterprise.tavrn.ai: a test key on production returns 401 invalid_api_key, a live key on the sandbox 400 wrong_environment.
Scopes per resource
A key carries read or write scopes for cases, documents, retrievals, requestors and webhooks, so a reconciliation job can hold read-only access.
Who issues keys
Sandbox keys are self-serve with a work email. Production keys are created by an organization admin in the Tavrn platform after onboarding.
Authentication guide

Idempotency

Retry any POST safely

A timeout on a POST leaves you unsure whether Tavrn processed it. Send an Idempotency-Key (1–255 characters, a UUID v4 is recommended) and Tavrn runs the operation once, replaying the stored outcome for 24 hours. Keys are scoped to the organization, so a retry still replays after a key rotation.

Request with the same keyResult
Same body, first request finishedThe original status and body, with Idempotent-Replayed: true
Different body422 idempotency_key_reused_with_different_payload
First request still running409 idempotency_key_in_use; retry after it completes
First request answered with a 5xxNothing is stored; the retry executes again
Same patient and facility already active (any key)409 duplicate_request_detected unless allow_duplicate is true; a separate check
Idempotency guide

Webhooks

Signed deliveries on every status change

Register an HTTPS endpoint with POST /v2/webhooks and choose the events. Each delivery carries the event id, type and timestamp and an HMAC-SHA256 signature over the timestamp and raw body in X-Tavrn-Signature-V1; verify it, store the event, return 2xx within five seconds.

Three retrieval events
retrieval_request.status_changed, retrieval_request.action_required when the team needs an answer, and retrieval_request.documents_available when files can be downloaded with the same key.
Retries and disabling
Up to nine attempts per event over about 72 hours, each with the same event id. After five consecutive failed events the endpoint is disabled and a webhook_endpoint.disabled event goes to your other endpoints; re-enable it with a PATCH.
Delivery log and redelivery
GET /v2/webhooks/{id}/deliveries lists every attempt for 90 days; any delivery can be queued again with the redeliver endpoint for 30 days.
Reconciliation without webhooks
GET /v2/events returns 30 days of events, and the request list accepts public_updated_since, so a poll can catch up after an outage.
Webhooks guide · Events guide

Sandbox

Synthetic data, the production contract

A separate deployment of the Enterprise API v2 for integration work before you have a Tavrn account: same endpoints, stages and webhook signatures; synthetic facilities and patients; test keys that never touch production.

  1. 01

    Sign up with a work email

    sandbox.tavrn.ai/sign-up issues a tavrn_sk_test_ key; free-mail and disposable addresses are rejected. The key page shows usage and rotates or revokes the key.

  2. 02

    Run the five calls

    Create a case, upload a synthetic authorization through sign-upload, open a retrieval request, read it, list its documents. Every call is the production call with the sandbox host and key.

  3. 03

    Pick a scenario

    The X-Tavrn-Sandbox-Scenario header drives the lifecycle: complete by default, no_records, action_required_payment and others. POST /v2/retrieval-requests/{id}/advance moves it forward now; it returns 404 on production.

  4. 04

    Go to production

    Sandbox limits: 25 retrieval requests, 3 webhook endpoints, 20 uploads, 300 requests a minute. An organization admin creates the live key after onboarding; only the host and the key change.

Compared with network APIs

Retrieval by request, not a network query

Particle Health, Health Gorilla and Metriport query the national health-data networks for a patient and return what participating organizations share. Tavrn requests the record from each provider the patient named, on the patient’s authorization, including providers outside every network. Many teams run both.

TopicTavrnParticle HealthHealth Gorilla Patient360Metriport
MechanismOne retrieval request per provider; Tavrn requests the custodian by network, release-of-information vendor, portal, fax, mail, email or phoneA query per registered patient across the Particle network (CommonWell and Carequality)A Patient360 query per patient across CommonWell, Carequality, eHealth Exchange and TEFCA QHINsA Network Query per patient across the connected health data networks, pharmacies and labs, with a webhook as each source completes
CoverageAny US provider: networks, vendors and portals return about 63% of a patient’s visits in Tavrn’s requests; the other 37% are requested directlyOrganizations participating in the networks Particle queriesOrganizations participating in the connected networks, plus Health Gorilla’s own HINOrganizations on the connected networks; Metriport’s docs note that about 95% of patients return data
Legal basisThe patient’s signed HIPAA authorization (45 CFR 164.508) naming your organization and purpose; no treatment relationship requiredNetwork purpose of use; CommonWell and Carequality are built on the treatment use caseClinical purposes under the networks’ purpose-of-use rulesProduction access requires a covered entity, an NPI and a treatment purpose of use
What comes backThe documents each provider released, searchable, with a download URL: records, bills, imaging reports and DICOM, pathology, as requestedClinical data in FHIR, flat or C-CDA formats, parsed from the network documentsFHIR R4 resources, with STU3 for Patient360 document retrievalA consolidated FHIR R4 record, with C-CDA and PDF on request
Getting startedSelf-serve sandbox key with a work email; production key from an organization admin after onboardingRegister a patient, then query; see the Particle docs for accessOAuth 2.0 and SMART on FHIR; a sandbox base URL alongside productionSandbox without the production requirements; open-source codebase
Vendor cells restate each vendor’s public documentation; Tavrn’s coverage figures are from its own request data.

Security

Controls for sensitive medical records

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

Security details

FAQ

The retrieval API, answered

What is the Tavrn medical record retrieval API?
A REST API (Enterprise API v2) that turns a patient’s signed authorization into retrieved records from any US provider. You create a case, attach the authorization, open one retrieval request per provider and subscribe to webhooks; Tavrn requests each custodian and posts each status change until the documents can be downloaded with the same key.
How does authentication work?
Every request sends an API key as Authorization: Bearer. Sandbox keys start with tavrn_sk_test_ and work only against the sandbox host; live keys start with tavrn_sk_live_, are created by an organization admin in the Tavrn platform, and carry read or write scopes per resource. Keys are shown once and can be rotated or revoked.
What happens if I retry a request after a timeout?
Send an Idempotency-Key header on the POST. Tavrn stores the first outcome for 24 hours and replays it for every retry with the same body, marked Idempotent-Replayed: true. A different body returns 422, a retry while the first request is still running returns 409, and 5xx outcomes are not stored, so the retry runs again.
Which webhook events are there, and how are they verified?
retrieval_request.status_changed, retrieval_request.action_required and retrieval_request.documents_available, plus webhook_endpoint.disabled when an endpoint is turned off after five consecutive failed events. Each delivery is signed with HMAC-SHA256 in X-Tavrn-Signature-V1; the secret is returned once and can be rotated with a 24-hour window in which both secrets sign.
What statuses does a retrieval request go through?
Five public statuses: received, processing, action_required, completed and cancelled. action_required carries a reason (an invoice over your approval threshold, a missing contact, an issue with the request) and is answered with the action-response endpoint; completed says whether records were returned or the provider had none on file. A finer stage field follows the request in between.
Is there a sandbox, and what does it cost?
Yes. The sandbox is self-serve: sign up at sandbox.tavrn.ai with a work email and get a tavrn_sk_test_ key, with synthetic facilities and patients and no production data. It serves the same endpoints, stages and webhook signatures as production. Production access is set up with your organization after onboarding.
How is this different from Particle Health, Health Gorilla or Metriport?
Those APIs query the national health-data networks for a patient and return what participating organizations share, as FHIR or C-CDA, under a treatment purpose of use. Tavrn requests the record from each provider the patient named, on the patient’s HIPAA authorization, including providers outside every network, and returns the documents as released. The two are complementary.
Can an AI agent use the API?
Yes. The reference is published as an OpenAPI document and as plain text at docs.tavrn.ai/llms.txt, and tavrn.ai/agents.md describes the API for agents. Sandbox sign-up is human-gated (a work email and a bot check), so an operator hands the agent the test key; from there every call is scriptable.

Start building

First request in four calls, on synthetic data

A sandbox key with a work email, or a demo to set up production access.

Get a sandbox keyDeveloper quickstart
Book a demo