3. First retrieval

A retrieval request tells Tavrn which patient’s records to get, from which facility, under which authorization. Tavrn finds the right contact at the facility, sends the request, follows up, pays the provider invoice under your limit, and returns the records. Endpoints: POST /v2/retrieval-requests/sign-upload and POST /v2/retrieval-requests. Scopes: retrievals:write, plus cases:write when the case is created inline.

What you need

A signed patient authorization (HIPAA release) as a PDF.
The patient’s name and date of birth.
A facility ID from facility search, or the facility’s name and address; dates of service if you have them.
The requestor_id from Firm setup (or omit it to use your default profile).

1. Upload the authorization

# Sign the upload; the response contains upload_url and upload_id
SIGNED=$(curl -s -X POST https://enterprise.tavrn.ai/v2/retrieval-requests/sign-upload \
  -H "Authorization: Bearer $TAVRN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "file_name": "authorization.pdf", "file_type": "application/pdf" }')
UPLOAD_URL=$(echo "$SIGNED" | jq -r .upload_url)
UPLOAD_ID=$(echo "$SIGNED" | jq -r .upload_id)

# PUT the bytes to the presigned URL
curl -X PUT "$UPLOAD_URL" -H "Content-Type: application/pdf" --data-binary @authorization.pdf

Upload the bytes within 15 minutes; use the returned upload_id within one hour.

2. Create the case and the request in one call

curl -X POST https://enterprise.tavrn.ai/v2/retrieval-requests \
  -H "Authorization: Bearer $TAVRN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "case": { "title": "Jane Doe — Example Matter", "client_name": "Jane Doe", "external_id": "MATTER-1001" },
    "requestor_id": "111111111111111111111111",
    "patient": { "name": "Jane Doe", "date_of_birth": "1990-01-01" },
    "facility": {
      "name": "Example General Hospital",
      "address_line1": "100 Example Ave",
      "city": "Springfield",
      "state": "IL",
      "zip_code": "62701"
    },
    "service_start_date": "2024-01-01",
    "service_end_date": "2024-06-30",
    "requested_records": [
      { "type": "medical_records" },
      { "type": "billings" }
    ],
    "auth_form": { "upload_id": "'$UPLOAD_ID'", "file_name": "authorization.pdf" }
  }'

If you selected a facility from search, replace the facility object with a top-level facility_id. Send exactly one of these fields. The response carries the new case_id, the requestor_id used, and the retrieval id (rr_…) with status: "received". Save the id; every later call and webhook refers to it. To add a request to an existing case, use case_id instead of case, or call POST /v2/cases/{case_id}/retrieval-requests. To use a profile you have not created yet, pass an inline requestor object instead of requestor_id (needs requestors:write).

Creation is not idempotent: each successful POST opens another request to the provider. Tavrn rejects an obvious duplicate for the same patient and facility unless you pass allow_duplicate: true; still check your own records before retrying a timeout.

Common options

Field	Use
`requested_records[].type`	`medical_records`, `medical_records_er`, `billings`, `radiology_reports`, `imaging`, … (full list in Requested Records)
`service_start_date` / `service_end_date`	Dates of service, on the request or per record line
`requested_records[].requirements`	`["affidavit"]` or `["certification"]`, one kind per request
`facility.fax` / `facility.phone`	If you already know the records department contact
`patient.address`, `patient.phone`, `patient.ssn`	Help the facility match the chart
`notes`	Free text for the retrieval team
`allow_duplicate`	Opt out of the duplicate check for the same patient and facility

Everything else is in the Retrieval guide.

Next: track it and download the records

Webhooks, polling, action requests, records and invoices.

Get started

Retrieval reference

Case documents

What you need

1. Upload the authorization

2. Create the case and the request in one call

Common options

Next: track it and download the records

​What you need

​1. Upload the authorization

​2. Create the case and the request in one call

​Common options

Next: track it and download the records

What you need

1. Upload the authorization

2. Create the case and the request in one call

Common options