Record Retrieval Guide

Overview

Use the Record Retrieval API to ask Tavrn to retrieve medical records, billing records, and provider invoices from a healthcare facility. The basic flow is:

Create or select a case and, if needed, configure a Requestor profile.
Upload the signed HIPAA authorization form and any profile documents.
Create a retrieval request.
Track the request with webhooks and incremental polling.
Download records and provider invoices as they become available.

What You’ll Need

API key with retrievals:write and retrievals:read scopes (plus cases:write if you’ll create the case via the API in step 1)
requestors:read if you’ll list or read Requestor profiles; requestors:write if you’ll create or configure one, including inline creation
A signed HIPAA authorization PDF for the patient
Patient name (date of birth if available)
A facility ID from facility search, or the facility name and address
At least one record type to request

Step-by-Step Guide

1. Create or Select a Case

Every new Enterprise API retrieval request needs a case. If you already have a case, skip to step 2 and use its id. Otherwise, create one:

curl -X POST https://enterprise.tavrn.ai/v2/cases \
  -H "Authorization: Bearer tavrn_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Jane Doe v. ACME Corp",
    "client_name": "Jane Doe"
  }'

Use the returned case id when you create the retrieval request. You can also create the case in the same call as its first retrieval using POST /v2/retrieval-requests. Upload files first using the retrieval upload endpoint, which does not require a case ID.

2. Upload the Authorization Form

Request an upload URL for the signed HIPAA authorization PDF:

curl -X POST https://enterprise.tavrn.ai/v2/cases/case_abc123/sign-upload \
  -H "Authorization: Bearer tavrn_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "jane_doe_hipaa.pdf",
    "file_type": "application/pdf"
  }'

The case upload endpoint accepts file_name and file_type for a retrieval attachment. Response:

{
  "upload_id": "11111111-1111-4111-8111-111111111111",
  "upload_url": "https://upload-url.example.com/...",
  "expires_at": "2025-02-01T13:34:56Z"
}

Upload the file to the returned upload_url:

curl -X PUT "https://upload-url.example.com/..." \
  -H "Content-Type: application/pdf" \
  --data-binary @jane_doe_hipaa.pdf

Save the upload_id. You will use it in auth_form when creating the retrieval request.

Upload supporting files the same way, one file per sign-upload call. Use the returned upload_id values in attachments.

3. Create the Retrieval Request

This minimal example requests medical records for one patient from one facility:

curl -X POST https://enterprise.tavrn.ai/v2/cases/case_abc123/retrieval-requests \
  -H "Authorization: Bearer tavrn_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "patient": {
      "name": "Jane Doe",
      "date_of_birth": "1989-04-12"
    },
    "facility": {
      "name": "Example General Hospital",
      "address_line1": "100 Example Ave",
      "city": "Springfield",
      "state": "PA",
      "zip_code": "00000",
      "fax": "+1-555-010-1111"
    },
    "service_start_date": "2024-03-15",
    "service_end_date": "2024-09-30",
    "requested_records": [
      {
        "type": "medical_records"
      }
    ],
    "auth_form": {
      "upload_id": "11111111-1111-4111-8111-111111111111",
      "file_name": "jane_doe_hipaa.pdf"
    }
  }'

Response (abridged):

{
  "id": "rr_abc123",
  "order_number": "T-ABC-12345",
  "case_id": "case_abc123",
  "requestor_id": "111111111111111111111111",
  "status": "received",
  "created_at": "2025-02-01T12:50:00Z",
  "updated_at": "2025-02-01T12:50:00Z"
}

Save the retrieval request id. Webhook events reference it as retrieval_request_id, and you use it to fetch status and download returned files. Both creation endpoints accept patient and requested_records, plus exactly one of a facility_id from search or a manual facility object:

Endpoint	Case selection	Requestor selection
`POST /v2/cases/{case_id}/retrieval-requests`	Uses the case in the URL; inline `case` is not accepted	Supply `requestor_id`, supply an inline `requestor`, or omit both for the organization default
`POST /v2/retrieval-requests`	Supply exactly one of an existing `case_id` or an inline `case` object	Supply `requestor_id`, supply an inline `requestor`, or omit both for the organization default

For organizations with duplicate detection enabled, creation can return 409 duplicate_request_detected with a duplicates array. Review those matches before retrying with "allow_duplicate": true if the new request is intentional.

Find a facility

Search by facility name, alias, phone, fax, address, or NPI using an API key with retrievals:read:

curl 'https://enterprise.tavrn.ai/v2/facilities?q=Example&state=PA&limit=5' \
  -H "Authorization: Bearer tavrn_sk_live_..."

{
  "results": [
    {
      "id": "facility_example",
      "name": "Example General Hospital",
      "requirements": []
    }
  ]
}

Choose a result and replace the facility object in your creation body with "facility_id": "facility_example". Send exactly one of facility_id or facility. If the API reports an invalid or expired facility selection, search again and use the new ID. Review any listed requirements before submitting. Each includes a label, optional description, category (input, document, or instruction), and applicable record_types; an empty record_types list means all record types. Document requirements may include template_download_url for a blank template. The link is valid for 1 hour; repeat the search for a fresh link. Search text must be 3–200 characters after trimming, with at least 3 alphanumeric characters. state is optional; limit is 1–10 and defaults to 10. Results are not paginated. On 429, wait for Retry-After; on 503, try again later.

Select a Requestor

A Requestor is a retrieval profile within your organization: its name, letter of representation, RFC form, affidavits, correspondence settings, and provider invoice approval limit. To use an existing profile, add its ID to the retrieval body:

{
  "requestor_id": "111111111111111111111111"
}

Omitting both requestor_id and requestor keeps the existing organization default. Each retrieval retains the selected ID. Configuration updates to that profile apply to its linked retrievals. Find available profiles with GET /v2/requestors, or read one with GET /v2/requestors/{requestor_id}. Both require requestors:read. List responses contain results, next, and previous; limit defaults to 20 and has a maximum of 100. Each profile includes is_default. An unavailable profile ID returns 404. If you need a different name, packet documents, correspondence settings, or invoice limit, you can create a reusable profile before submitting the retrieval. Give it a nonblank name using POST /v2/requestors, which requires requestors:write:

curl -X POST https://enterprise.tavrn.ai/v2/requestors \
  -H "Authorization: Bearer $TAVRN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example Firm — Records Team",
    "provider_invoice_limit": 150
  }'

Omitted document and correspondence settings start empty. An omitted invoice limit uses $100. Creating a profile does not change the default profile. Each successful POST creates another profile. Save the returned id and use it as requestor_id for this and later retrievals. You can also supply an inline requestor on either retrieval creation endpoint; it requires requestors:write and cannot be combined with requestor_id.

Upload Requestor Documents

To include a letter of representation in retrieval packets, upload it to the selected profile. A profile without its own document does not use the default profile’s document. Request an upload URL with POST /v2/requestors/sign-upload, then PUT the PDF bytes to the returned upload_url:

curl -X POST https://enterprise.tavrn.ai/v2/requestors/sign-upload \
  -H "Authorization: Bearer $TAVRN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "file_name": "letter-of-representation.pdf", "file_type": "application/pdf" }'

curl -X PUT "https://upload-url.example.com/..." \
  -H "Content-Type: application/pdf" \
  --data-binary @letter-of-representation.pdf

Use the returned upload_id in the profile create or update body. Profile documents must be readable, unencrypted PDFs with a .pdf extension and application/pdf type, of at most 25 MiB. Upload bytes within 15 minutes; the upload ID expires after one hour. These upload IDs are for Requestor documents. Authorization forms and retrieval attachments use the retrieval upload endpoint. For example, attach the uploaded letter to an existing profile with PATCH /v2/requestors/{requestor_id}:

curl -X PATCH https://enterprise.tavrn.ai/v2/requestors/111111111111111111111111 \
  -H "Authorization: Bearer $TAVRN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "letter_of_rep": { "upload_id": "11111111-1111-4111-8111-111111111111" }
  }'

Read responses include document metadata such as file_name, page_count, and uploaded_at.

Create a Case and Requestor Inline

Use POST /v2/retrieval-requests to create the case, Requestor, and retrieval in one request. This request requires retrievals:write, cases:write, and requestors:write. First upload the signed authorization through POST /v2/retrieval-requests/sign-upload. For profile documents such as the letter of representation, follow Upload Requestor Documents. Both take file_name and file_type; PUT each file to its returned upload_url. Use each upload ID with the matching document field. Upload the bytes within 15 minutes and use the upload_id within one hour.

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"
    },
    "requestor": {
      "name": "Example Firm — Records Team",
      "provider_invoice_limit": 150,
      "letter_of_rep": {
        "upload_id": "11111111-1111-4111-8111-111111111111"
      }
    },
    "patient": {
      "name": "Jane Doe",
      "date_of_birth": "1990-01-01"
    },
    "facility": {
      "name": "Example Clinic",
      "address_line1": "123 Example Street",
      "city": "Springfield",
      "state": "IL",
      "zip_code": "62701"
    },
    "requested_records": [{ "type": "medical_records" }],
    "auth_form": {
      "upload_id": "22222222-2222-4222-8222-222222222222",
      "file_name": "authorization.pdf"
    }
  }'

The response includes the new case_id, requestor_id, and retrieval id. Upload files before creating the retrieval. POST creation is not idempotent: each successful request with an inline case or requestor creates a new one. Retain the returned IDs and use case_id and requestor_id for subsequent retrievals. Use case_id instead of case for an existing case, and requestor_id instead of requestor for an existing profile. Exactly one case choice is required. Do not send both alternatives for either resource. The case-scoped creation endpoint continues to use the case in its URL and does not accept an inline case.

Update Requestor Settings

Use PATCH /v2/requestors/{requestor_id} to update a profile’s settings for linked retrievals. It requires requestors:write and at least one field. Omitted fields remain unchanged.

Setting	Behavior
`name`	A nonblank override, or `null` to use the organization name.
`provider_invoice_limit`	Nonnegative USD amount. `null` uses $100; `0` prevents automatic payment of positive provider costs.
`letter_of_rep`, `rfc_form`	An `upload_id` replaces the document; `null` removes it.
`affidavits.declared_families`	Replaces the declaration; `[]` records an explicit answer of none, including on a new profile. Omitting the declaration without uploading exact-family documents leaves it unanswered or preserves the previous answer. Families are `records`, `billing`, and `radiology`. When omitted, supplied document families are added to the current declaration.
`affidavits.documents`	Replaces all exact-family documents. Each entry has `family` and `upload_id`; one entry per family. `[]` removes them all. If `declared_families` is supplied too, it must include every uploaded family.
`affidavits.generic`	A fallback affidavit upload, or `null` to remove it. Updating exact-family documents leaves it unchanged.
`correspondence`	Omitted settings stay unchanged; `null` clears all overrides. A supplied `notice` replaces the notice; supplied `billing_request` fields merge.

Read responses include effective_provider_invoice_limit, so you can see the limit used when provider_invoice_limit is null. The API does not delete profiles, change the organization default, or reassign an existing retrieval to another profile.

4. Track Status

Subscribe to retrieval request webhooks for status updates, action requests, and available records or invoices:

Event	When it fires
`retrieval_request.status_changed`	A public status or timeline change, including another update within the same stage
`retrieval_request.action_required`	An action request is opened or reopened for your firm
`retrieval_request.documents_available`	A new record or provider invoice is available

When an event arrives, use its retrieval request ID to fetch the current request:

curl https://enterprise.tavrn.ai/v2/retrieval-requests/rr_abc123 \
  -H "Authorization: Bearer tavrn_sk_live_..."

Use status for the overall request state and stage to show its progress in Tavrn. status values:

Status	Meaning
`received`	Request submitted and queued
`processing`	Tavrn is working the request with the facility (including handling any provider invoice)
`action_required`	Tavrn needs something from your firm before it can continue
`completed`	Records were received and are available for download
`cancelled`	Request was cancelled before completion

completed and cancelled are final statuses. Both trigger a retrieval_request.status_changed event. Continue incremental polling to pick up later document changes.

When status is action_required, read pending_action_request for what your firm needs to provide. Respond through the API or follow platform_url to handle it in Tavrn. After a response, the request returns to processing.

stage values:

Stage	Label	Meaning
`submitted`	Submitted	Request received by Tavrn
`locating_contact`	Retrieving Contact	Finding the best way to reach the facility
`contact_found`	Contact Retrieved	Facility contact confirmed; request about to be sent
`request_sent`	Correspondence Sent	Request sent to the facility (fax, mail, email, or portal)
`confirming_receipt`	Confirming Receipt	Following up to confirm the facility received the request
`acknowledged`	Request Acknowledged	Facility confirmed receipt and is processing the request
`invoice_received`	Invoice Received	The facility sent an invoice; Tavrn is processing it
`action_required`	Action Required	Your firm needs to respond (see note above)
`completed`	Completed	Records are available for download
`cancelled`	Cancelled	Request was cancelled

stage_label and stage_description carry the exact text shown on the dashboard for the current stage. Not every request passes through every stage — for example, a request whose facility contact is already known goes straight to request_sent. Example response (abridged):

{
  "id": "rr_abc123",
  "status": "processing",
  "action_required_reason": null,
  "stage": "acknowledged",
  "stage_label": "Request Acknowledged",
  "stage_description": "Your request is in progress with the provider. We follow up with them regularly and will post updates here.",
  "timeline": [
    {
      "stage": "submitted",
      "stage_label": "Submitted",
      "state": "completed",
      "occurred_at": "2025-02-01T12:50:00Z",
      "description": "Request submitted for processing.",
      "checkpoints": [],
      "action_request": null
    },
    {
      "stage": "locating_contact",
      "stage_label": "Retrieving Contact",
      "state": "completed",
      "occurred_at": "2025-02-01T14:02:00Z",
      "description": "We are searching for the best way to send out requests for this provider.",
      "checkpoints": [
        { "text": "Call completed at 2:14 PM to the facility.", "occurred_at": "2025-02-01T19:14:00Z" }
      ],
      "action_request": null
    },
    {
      "stage": "contact_found",
      "stage_label": "Contact Retrieved",
      "state": "skipped",
      "occurred_at": null,
      "description": null,
      "checkpoints": [],
      "action_request": null
    },
    {
      "stage": "request_sent",
      "stage_label": "Correspondence Sent",
      "state": "completed",
      "occurred_at": "2025-02-02T10:30:00Z",
      "description": "We've sent out your request via fax and will be following up with the provider to check in on progress.",
      "checkpoints": [],
      "action_request": null
    },
    {
      "stage": "confirming_receipt",
      "stage_label": "Confirming Receipt",
      "state": "skipped",
      "occurred_at": null,
      "description": null,
      "checkpoints": [],
      "action_request": null
    },
    {
      "stage": "acknowledged",
      "stage_label": "Request Acknowledged",
      "state": "current",
      "occurred_at": "2025-02-04T09:14:21Z",
      "description": "Your request is in progress with the provider. We follow up with them regularly and will post updates here.",
      "checkpoints": [],
      "action_request": null
    },
    {
      "stage": "completed",
      "stage_label": "Completed",
      "state": "pending",
      "occurred_at": null,
      "description": null,
      "checkpoints": [],
      "action_request": null
    }
  ]
}

Each timeline entry has a state: completed (happened), current (where the request is now), pending (standard step not reached yet), or skipped (standard step that was not needed). checkpoints list individual attempts within a step, such as phone calls. action_request is set on action_required steps and includes what was asked, whether your firm has responded (awaiting_response, answered, or resolved), and the response text.

timeline is returned by GET /v2/retrieval-requests/{id} and list queries with include=details. Summary list results include stage, stage_label, and stage_description but omit the timeline.

Filtering the list by stage:

curl "https://enterprise.tavrn.ai/v2/retrieval-requests?stage=request_sent,acknowledged" \
  -H "Authorization: Bearer tavrn_sk_live_..."

stage accepts one or more comma-separated values and can be combined with status and case_id.

Incremental polling

Use public_updated_since with the list endpoint to reconcile status, action request, and document updates alongside webhooks:

curl 'https://enterprise.tavrn.ai/v2/retrieval-requests?public_updated_since=1970-01-01T00%3A00%3A00.000Z&include=details&limit=100' \
  -H 'Authorization: Bearer tavrn_sk_live_...'

Start with your saved checkpoint, or the epoch timestamp above for an initial sync.
Upsert each result by request ID. include=details adds the timeline, open action request, and released document metadata.
Follow each next URL as returned until it is null.
After processing the final page, save its next_public_updated_since for the next round.

The lower bound is inclusive, so a request may appear in successive rounds. Compare public_updated_at when updating a cached request. The final page supplies next_public_updated_since even when no requests were returned. For an organization-wide sync, leave status, stage, and case filters unset so completed and cancelled requests stay in scope. You can divide a large initial sync into fixed creation-date windows, with a checkpoint for each window. Choose a polling interval that fits your integration. Changes during a round may appear in that round or the next. If a cursor expires or polling returns 503, resume from the last saved checkpoint. Fetch an individual request when you need current costs.

5. Download Records and Invoices

List documents when you receive retrieval_request.documents_available or need current files. Provider invoices can become visible before or after request completion:

curl https://enterprise.tavrn.ai/v2/retrieval-requests/rr_abc123/documents \
  -H "Authorization: Bearer tavrn_sk_live_..."

Response:

{
  "results": [
    {
      "id": "rrdoc_001",
      "retrieval_request_id": "rr_abc123",
      "category": "records",
      "record_types": ["medical_records"],
      "file_name": "example_general_hospital_records.pdf",
      "file_size": 2456789,
      "file_type": "application/pdf",
      "page_count": 134,
      "created_at": "2025-02-05T15:22:10Z"
    },
    {
      "id": "65c12ab34de56f7890123456",
      "retrieval_request_id": "rr_abc123",
      "category": "invoice",
      "record_types": [],
      "metadata": {
        "provider_fee_amount": 85
      },
      "file_name": "example_general_hospital_invoice.pdf",
      "file_size": 45123,
      "file_type": "application/pdf",
      "page_count": 1,
      "created_at": "2025-02-05T15:22:11Z"
    }
  ],
  "next": null,
  "previous": null
}

This endpoint returns all current documents in one response. next and previous are always null. Use category to distinguish records, provider invoice documents, and cost_summary PDFs. Each invoice entry includes metadata.provider_fee_amount: the invoice amount in USD, not cents, that contributes to costs.provider_fees. 0 is a valid amount. Record and cost summary entries omit metadata. The embedded documents array on GET /v2/retrieval-requests/{id} and the document list use the same entries. A documents_available event’s document_ids and invoice_ids match their id values. An invoice can appear in the list and costs before it is downloadable. In that case, its download route returns 404. The invoice documents_available webhook fires when the file becomes downloadable. Get a download URL for each document:

curl https://enterprise.tavrn.ai/v2/retrieval-requests/rr_abc123/documents/rrdoc_001/download \
  -H "Authorization: Bearer tavrn_sk_live_..."

Response:

{
  "download_url": "https://download-url.example.com/...",
  "expires_in": 3600
}

Download the file from download_url before it expires.

Request cost PDF

Once a request is completed and its billing is finalized, its documents include an entry with id and category both set to cost_summary. The PDF shows Tavrn credits and fees, provider fees, and the total. It always includes a Tavrn credits line, showing 0 credits × $0.00 = $0.00 when the request has no credit entries.

curl https://enterprise.tavrn.ai/v2/retrieval-requests/rr_abc123/documents/cost_summary/download \
  -H "Authorization: Bearer tavrn_sk_live_..."

The response contains download_url and expires_in: 3600. Fetch the URL to download the PDF. The endpoint returns 404 while the document is unavailable. The entry appears in the request GET response and list results with include=details, but is excluded from documents_summary counts. Refetch the request or document list to check availability: billing finalization does not trigger a documents_available webhook or advance public_updated_at.

Invoice Availability Notifications

Subscribe to retrieval_request.documents_available through Webhooks to learn when a document becomes downloadable. When a provider invoice becomes downloadable, the request’s public_updated_at advances and the event identifies the available invoice:

{
  "id": "rr-1027bfb56ac889adef3b3b8266d758322502c10b6b64499224218c9e3e2919f0",
  "type": "retrieval_request.documents_available",
  "created_at": "2026-10-08T12:03:00.000Z",
  "data": {
    "retrieval_request_id": "507f1f77bcf86cd799439011",
    "case_id": "507f1f77bcf86cd799439012",
    "public_updated_at": "2026-10-08T12:03:00.000Z",
    "document_ids": ["507f1f77bcf86cd799439015"],
    "invoice_ids": ["507f1f77bcf86cd799439015"]
  }
}

For an invoice, its ID appears in both document_ids and invoice_ids. Use it as {document_id} on the download route, and fetch the request for current document and cost details.

Retrieval documents are separate from case documents you upload for other workflows. Their metadata is available from /v2/retrieval-requests/{id}/documents, the request GET response, and list queries with include=details. Use the retrieval document download endpoint to access the files.

Optional Fields

The minimal request works with patient name, a facility ID or facility name and address, at least one record type, and an authorization form. Add these fields when you have them:

Field	Notes
`patient.address`, `patient.phone`, `patient.email`, `patient.gender`, `patient.ssn`	Helps the facility verify the patient
`facility.phone`, `facility.fax`	Helps Tavrn contact the facility
`service_start_date`, `service_end_date`	Default date range for requested records
`notes`	Instructions for the team handling this request
`submitter_email`	Email of a user in your organization to attribute the request to — they receive retrieval notifications for it. Must match an existing user in your organization (otherwise the request fails with a `400 validation_error`). If omitted, the request is attributed to the API key’s creator
`attachments`	Additional uploaded files, such as cover letters or patient ID copies
`allow_duplicate`	After a `409 duplicate_request_detected` response, set to `true` to submit despite the returned matches

Requested Records

Use requested_records to describe what you want from the facility. Medical records only:

{
  "requested_records": [
    { "type": "medical_records" }
  ]
}

Medical records plus itemized billing:

{
  "requested_records": [
    { "type": "medical_records" },
    { "type": "billings", "deliverable_format": "itemized" }
  ]
}

Certified medical records:

{
  "requested_records": [
    { "type": "medical_records", "requirements": ["certification"] }
  ]
}

A request may use only one attestation kind — certification or affidavit — across all of its requested_records. Mixing them (on the same or different lines) returns a 400 validation_error; submit a separate request for records that need the other kind. Ongoing care: Set service_end_date to null to request records through the present.

{
  "requested_records": [
    {
      "type": "medical_records",
      "service_start_date": "2024-01-01",
      "service_end_date": null
    }
  ]
}

Some values, including rfc, abstract_medical_records, and requirements, are available only when enabled for your organization. See Permission-gated features.

See the RequestedRecord schema for the full list of record types, billing formats, and advanced patterns.

Responding to Action Requests

When Tavrn needs something from your firm, the request’s status becomes action_required and GET /v2/retrieval-requests/{id} returns the open action request in pending_action_request:

{
  "id": "rr_abc123",
  "status": "action_required",
  "action_required_reason": "payment_needed",
  "pending_action_request": {
    "id": "car_abc123",
    "description": "The provider's invoice of $85.00 exceeds your approval limit. Do you approve payment?",
    "document": {
      "file_name": "provider_invoice.pdf",
      "file_size": 45123,
      "file_type": "application/pdf",
      "download_url": "https://s3.amazonaws.com/...",
      "expires_in": 3600
    }
  }
}

document is a file Tavrn attached to the action request (for example, a provider invoice or no-records letter), or null. Its download_url expires after expires_in seconds; fetch the request for a fresh URL. When an action request opens or reopens, retrieval_request.action_required includes its ID. Fetch the request to read the message and any attachment; incremental polling also captures the update.

Text-only response

curl -X POST https://enterprise.tavrn.ai/v2/retrieval-requests/rr_abc123/action-response \
  -H "Authorization: Bearer tavrn_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Approved. Please pay the $85.00 invoice.",
    "requester_email": "paralegal@yourfirm.com"
  }'

Response:

{
  "id": "car_abc123",
  "retrieval_request_id": "rr_abc123",
  "status": "responded",
  "responded_at": "2025-02-03T16:05:00Z"
}

message is required (up to 10,000 characters). requester_email is optional and records who at your firm answered. The endpoint needs the retrievals:write scope.

Response with an attachment

Upload the file under the retrieval request’s case, then pass its upload_id:

# 1. Get a presigned upload URL for the request's case
curl -X POST https://enterprise.tavrn.ai/v2/cases/case_abc123/sign-upload \
  -H "Authorization: Bearer tavrn_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "file_name": "signed_hipaa_authorization.pdf", "file_type": "application/pdf" }'

# 2. Upload the file to the returned upload_url
curl -X PUT "<upload_url>" \
  -H "Content-Type: application/pdf" \
  --data-binary @signed_hipaa_authorization.pdf

# 3. Answer the action request with the upload_id
curl -X POST https://enterprise.tavrn.ai/v2/retrieval-requests/rr_abc123/action-response \
  -H "Authorization: Bearer tavrn_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Signed authorization attached.",
    "attachment": { "upload_id": "11111111-1111-4111-8111-111111111111" }
  }'

The upload must belong to the same case as the retrieval request. PUT the file to the signed URL within 15 minutes, then use its upload_id within one hour. Each upload_id can be used once.

How Tavrn handles your response

Action request	What to send	What happens
Missing HIPAA authorization	A signed authorization PDF as `attachment` (required)	The PDF replaces the request’s authorization form and Tavrn restarts the request. A text-only answer or a non-PDF file is rejected with `400`
Invalid HIPAA authorization	A corrected, signed PDF as `attachment`, or a text update	A PDF replaces the authorization form and Tavrn restarts the request. A non-PDF file is rejected with `400`
Payment approval (`action_required_reason: payment_needed`)	A clear approval or decline in `message`, e.g. `Approved to pay $85.00`	Tavrn pays only when your answer clearly approves this invoice at the quoted amount. A decline, a lower cap, or a question is reviewed by the Tavrn team
No records found	Confirm the provider’s statement, or explain what to correct	A confirmation completes the request with the provider’s no-records statement. A correction, dispute, or attachment is reviewed by the Tavrn team
Missing portal information (e.g. SSN last 4, sex, address)	The requested values in `message`	Tavrn fills the provider portal and resubmits. An answer it cannot read is rejected with `400`
Anything else	Your answer in `message`, with an `attachment` if asked for a document	The Tavrn team reviews your answer and continues the request

A rejected response (400) leaves the action request open so you can retry. After a successful response the request leaves action_required (usually back to processing), and the timeline’s action_request shows status: "answered" with your response_text. Responding again after that returns 409, as does responding when there is no open action request.

Support messages

Send a question or instruction with POST /v2/retrieval-requests/{retrieval_request_id}/messages. Requires retrievals:write and, for CMS-linked requests, support messaging enabled on the connection.

curl -X POST https://enterprise.tavrn.ai/v2/retrieval-requests/rr_abc123/messages \
  -H "Authorization: Bearer tavrn_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Please confirm whether the provider has accepted this request.",
    "requester_name": "Jane Doe",
    "requester_email": "jane@example.com",
    "contact_preference": "email"
  }'

`contact_preference`	Behavior
`email` (default)	Email receipts and replies. Supply `requester_email` when explicitly selecting this option.
`in_app_only`	Log published replies without email. Automated replies are currently disabled.
`do_not_contact`	Process requested work without receipts or replies. Only Litify-originated submissions keep the initial email receipt.

Messages and published replies are logged without changing retrieval status. Drafts and private notes are excluded. message is required (maximum 10,000 characters). Upload attachments under the request’s case, then include attachment: { "upload_id": "..." }. Identical submissions within 10 minutes return the existing conversation with deduplicated: true. Concurrent submissions return 409 (support_message_in_progress); retry shortly. Success confirms submission, not completion of the requested work.

Cancelling a Request

You can cancel a request before it completes:

curl -X POST https://enterprise.tavrn.ai/v2/retrieval-requests/rr_abc123/cancel \
  -H "Authorization: Bearer tavrn_sk_live_..."

Cancellation is final. Completed requests cannot be cancelled.

Get started

Retrieval reference

Case documents

Overview

What You’ll Need

Step-by-Step Guide

1. Create or Select a Case

2. Upload the Authorization Form

3. Create the Retrieval Request

Find a facility

Select a Requestor

Upload Requestor Documents

Create a Case and Requestor Inline

Update Requestor Settings

4. Track Status

Incremental polling

5. Download Records and Invoices

Request cost PDF

Invoice Availability Notifications

Optional Fields

Requested Records

Responding to Action Requests

Text-only response

Response with an attachment

How Tavrn handles your response

Support messages

Cancelling a Request

Next Steps

​Overview

​What You’ll Need

​Step-by-Step Guide

​1. Create or Select a Case

​2. Upload the Authorization Form

​3. Create the Retrieval Request

​Find a facility

​Select a Requestor

​Upload Requestor Documents

​Create a Case and Requestor Inline

​Update Requestor Settings

​4. Track Status

​Incremental polling

​5. Download Records and Invoices

​Request cost PDF

​Invoice Availability Notifications

​Optional Fields

​Requested Records

​Responding to Action Requests

​Text-only response

​Response with an attachment

​How Tavrn handles your response

​Support messages

​Cancelling a Request

​Next Steps

Overview

What You’ll Need

Step-by-Step Guide

1. Create or Select a Case

2. Upload the Authorization Form

3. Create the Retrieval Request

Find a facility

Select a Requestor

Upload Requestor Documents

Create a Case and Requestor Inline

Update Requestor Settings

4. Track Status

Incremental polling

5. Download Records and Invoices

Request cost PDF

Invoice Availability Notifications

Optional Fields

Requested Records

Responding to Action Requests

Text-only response

Response with an attachment

How Tavrn handles your response

Support messages

Cancelling a Request

Next Steps