> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tavrn.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 3. First retrieval

> Upload the signed authorization and create a case and retrieval request in one call.

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`](/api-reference/v2/endpoint/retrieval-requests/sign-upload)
and [`POST /v2/retrieval-requests`](/api-reference/v2/endpoint/retrieval-requests/create-with-case-and-requestor).
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](/guides/v2/retrieval-guide#find-a-facility), or the facility's name and address; dates of service if you have them.
* The `requestor_id` from [Firm setup](/guides/v2/get-started/firm-setup) (or omit it to use
  your default profile).

## 1. Upload the authorization

```bash theme={null}
# 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

```bash theme={null}
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`](/api-reference/v2/endpoint/retrieval-requests/create-retrieval-request).
To use a profile you have not created yet, pass an inline `requestor` object instead of
`requestor_id` (needs `requestors:write`).

<Note>
  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.
</Note>

## Common options

| Field | Use |
| - | - |
| `requested_records[].type` | `medical_records`, `medical_records_er`, `billings`, `radiology_reports`, `imaging`, … (full list in [Requested Records](/guides/v2/retrieval-guide#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](/guides/v2/retrieval-guide#optional-fields).

<Card title="Next: track it and download the records" icon="arrow-right" href="/guides/v2/get-started/track-and-download">
  Webhooks, polling, action requests, records and invoices.
</Card>