> ## 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.

# Data Models & Schemas

> Complete data model documentation for Enterprise API v2

## Overview

This page documents all data models used in the Enterprise API v2. All field names use `snake_case` and timestamps are in ISO 8601 format.

## Case

Represents a legal case in your organization.

| Field | Type | Required | Description |
| - | - | - | - |
| `id` | string | Yes (read-only) | Unique case identifier (e.g., `case_abc123`) |
| `case_number` | string | Yes (read-only) | Auto-generated case number (e.g., `EI-2025-0001`) |
| `title` | string | Yes | Case title (e.g., "Jane Doe v. ACME Corp") |
| `client_name` | string | Yes | Client's name |
| `description` | string | No | Case description |
| `client_date_of_birth` | string (date) | No | Client's DOB (YYYY-MM-DD) |
| `client_address` | string | No | Client's address |
| `client_phone` | string | No | Client's phone number |
| `client_email` | string (email) | No | Client's email |
| `date_of_injury` | string (date) | No | Injury date (YYYY-MM-DD, must be in past) |
| `deposition_date` | string (date) | No | Deposition date (YYYY-MM-DD) |
| `case_category` | string (enum) | No on create | Category (defaults to `personal_injury`; always returned on read) |
| `status` | string (enum) | No on create | Status (defaults to `active`; always returned on read) |
| `external_id` | string | No | External identifier for mapping |
| `created_at` | string (datetime) | Yes (read-only) | Creation timestamp |
| `updated_at` | string (datetime) | Yes (read-only) | Last update timestamp |

### Enumerations

**case\_category** values accepted when creating a case, including an inline `case` on a retrieval request:

* `personal_injury`
* `motor_vehicle_accident`
* `medical_malpractice`
* `workers_compensation`
* `product_liability`
* `premises_liability`
* `wrongful_death`
* `other`

**status** values accepted when creating a case:

* `active`
* `pending`
* `closed`

## Document

Represents an uploaded document associated with a case.

| Field | Type | Required | Description |
| - | - | - | - |
| `id` | string | Yes (read-only) | Unique document identifier |
| `case_id` | string | Yes | Associated case ID |
| `file_name` | string | Yes | File name (e.g., "medical\_record.pdf") |
| `file_size` | integer | Yes | File size in bytes |
| `file_type` | string | Yes | MIME type (e.g., "application/pdf") |
| `path` | string | No | Virtual path for UI grouping (e.g., "Example\_General\_Hospital") |
| `archived` | boolean | Yes | Whether document is archived |
| `created_at` | string (datetime) | Yes (read-only) | Creation timestamp |
| `updated_at` | string (datetime) | Yes (read-only) | Last update timestamp |

## RetrievalRequest

Represents a medical record retrieval request submitted to a healthcare provider on behalf of a patient.

| Field | Type | Required | Description |
| - | - | - | - |
| `id` | string | Yes (read-only) | Unique retrieval request identifier (e.g., `rr_abc123`) |
| `order_number` | string or null | Yes (read-only) | Human-readable order number (e.g., `T-ABC-12345`), when available |
| `case_id` | string or null | Create choice or URL; always on read | Existing case ID on standalone create, or the case in the case-scoped URL. Inline `case` replaces `case_id` on standalone create. Can be `null` on read |
| `requestor_id` | string or null | No on create; always on read | Selected [Requestor](/guides/v2/retrieval-guide#select-a-requestor) profile ID. Supply an existing profile on create; omit it and `requestor` to use the default. A `null` read value uses the default profile |
| `requestor` | object | No (create-only) | Create a Requestor profile with this retrieval. Requires `requestors:write` and cannot be combined with `requestor_id` |
| `platform_url` | string (uri) | No (read-only) | Deep link to this retrieval request on the Tavrn platform dashboard; `null` when the request has no linked case |
| `status` | string (enum) | Yes (read-only) | Coarse public retrieval status (see below) |
| `action_required_reason` | string (enum) | No (read-only) | Sub-reason when `status` is `action_required` (see below); `null` otherwise |
| `stage` | string (enum) | Yes (read-only) | Lifecycle stage as shown on the Tavrn platform dashboard (see below) |
| `stage_label` | string | Yes (read-only) | Dashboard label for `stage`, e.g. `Request Acknowledged` |
| `stage_description` | string | No (read-only) | Dashboard sentence for the current stage; `null` when there is nothing to show yet |
| `timeline` | array\[[RetrievalTimelineEntry](#retrievaltimelineentry)] | Get or `include=details` (read-only) | Ordered lifecycle steps as rendered on the dashboard. Omitted from ordinary list results |
| `pending_action_request` | object ([PendingActionRequest](#pendingactionrequest)) or null | Get or `include=details` (read-only) | The open action request your firm needs to answer; `null` when there is none. Omitted from ordinary list results |
| `patient` | object ([Patient](#patient)) | Yes | Patient details |
| `facility` | object ([Facility](#facility)) | Create choice; always on read | Facility details. On create, provide this object or `facility_id` |
| `facility_id` | string | Create choice (create-only) | ID from [facility search](/api-reference/v2/endpoint/facilities/search-facilities). Provide exactly one of `facility_id` or `facility` |
| `requested_records` | array\[[RequestedRecord](#requestedrecord)] | Yes | One or more record lines to request from the facility. Each line carries its own type, dates, and (for billing) deliverable format |
| `service_start_date` | string (date) | No | Default start of the service date range (YYYY-MM-DD). Inherited by any `requested_records[]` line that omits its own |
| `service_end_date` | string (date) or null | No | Default end of the service date range (YYYY-MM-DD). Inherited by any line that omits its own. `null` = ongoing / "Present" |
| `notes` | string | No | Free-text instructions for the team handling this request |
| `submitter_email` | string (email) | No (create-only) | Email of the user in your organization to attribute the request to. That user receives retrieval notifications for the request. Must match an existing user in your organization or the request is rejected with a `400 validation_error`. Defaults to the creator of the API key |
| `allow_duplicate` | boolean | No (create-only) | When duplicate detection is enabled and creation returns `409 duplicate_request_detected`, set to `true` only after reviewing the returned matches and deciding to submit anyway |
| `auth_form` | object ([AuthFormUpload](#authformupload)) | Yes (on create) | The signed HIPAA authorization PDF, plus optional signer metadata if not signed by the patient |
| `attachments` | array\[[UploadedFile](#uploadedfile)] | No (create-only) | Supporting documents (cover letters, patient ID copies, prior-auth forms) |
| `documents_summary` | object | Yes (read-only) | `{ "records_count": integer, "invoices_count": integer }`; counts records and provider invoices; excludes cost summaries |
| `documents` | array\[[RetrievalRequestDocument](#retrievalrequestdocument)] | Get or `include=details` (read-only) | Available records, provider invoices, and a cost summary for completed requests with finalized billing. Omitted from ordinary list results |
| `costs` | object ([RetrievalRequestCosts](#retrievalrequestcosts)) | Get endpoint only (read-only) | Current request cost breakdown, in USD. Omitted from all list results, even with `include=details` |
| `created_at` | string (datetime) | Yes (read-only) | Creation timestamp |
| `updated_at` | string (datetime) | Yes (read-only) | Last update timestamp |
| `public_updated_at` | string (datetime) or null | Yes (read-only) | Timestamp for public request changes, including status, action requests, and documents. Costs may change without advancing it. For polling, save the list response's `next_public_updated_since` |
| `completed_at` | string (datetime) | No (read-only) | Completion timestamp (null until terminal) |

On `POST /v2/retrieval-requests`, provide exactly one of `case_id` (an existing case) or `case` (an inline [Case](#case) create body). Creating the case inline requires `cases:write`. The case-scoped create route takes its case ID from the URL and does not accept an inline `case`. GET and list responses omit the create-only `auth_form` and `attachments` upload references.

### Enumerations

**status** — a simplified, stable enum suitable for client routing logic:

| Status | Meaning |
| - | - |
| `received` | Request submitted, queued for processing |
| `processing` | Tavrn is contacting the facility and awaiting records |
| `action_required` | Tavrn needs a response from your firm before it can continue (see `action_required_reason` and the current `timeline` entry's `action_request`) |
| `completed` | Records received and available for download |
| `cancelled` | Request was cancelled before completion |

**action\_required\_reason** (only set when `status` is `action_required`):

* `payment_needed` — A provider fee needs your approval or payment
* `contact_missing` — Facility contact details could not be confirmed
* `request_issue` — Facility flagged an issue with the request
* `other` — Catch-all

**stage** — the lifecycle step shown on the Tavrn platform dashboard:

| Stage | Label |
| - | - |
| `submitted` | Submitted |
| `locating_contact` | Retrieving Contact |
| `contact_found` | Contact Retrieved |
| `request_sent` | Correspondence Sent |
| `confirming_receipt` | Confirming Receipt |
| `acknowledged` | Request Acknowledged |
| `invoice_received` | Invoice Received |
| `action_required` | Action Required |
| `completed` | Completed |
| `cancelled` | Cancelled |

See the [Record Retrieval Guide](/guides/v2/retrieval-guide#4-track-status) for what each stage means and a full example.

## RetrievalRequestCosts

`GET /v2/retrieval-requests/{id}` returns current costs for a request. Amounts are
in USD, not cents. Costs can change after completion without advancing
`public_updated_at` or producing a webhook, so fetch the request again when you
need current costs.

| Field | Type | Description |
| - | - | - |
| `tavrn_credits_consumed` | number or null | Credits consumed, net of refunds; `null` when unavailable |
| `tavrn_fee` | number or null | Tavrn fee for the request; `null` when unavailable |
| `provider_fees` | number | Sum of returned provider invoice amounts; `0` when none are available |
| `total_cost` | number or null | `tavrn_fee` plus `provider_fees`; `null` when `tavrn_fee` is unavailable |

## RetrievalTimelineEntry

One step of a [RetrievalRequest](#retrievalrequest) `timeline`, mirroring a row of the dashboard's status stepper. The standard steps (`submitted` through `acknowledged`, plus `completed`) always appear; `invoice_received`, `action_required` and `cancelled` appear only when they occurred, and `action_required` repeats once per action request.

| Field | Type | Description |
| - | - | - |
| `stage` | string (enum) | Stage this step belongs to (see `stage` above) |
| `stage_label` | string | Label for this step. An answered action request shows `Action Response Received` |
| `state` | string (enum) | `completed`, `current`, `pending` (standard step not reached yet), or `skipped` (standard step not needed for this request) |
| `occurred_at` | string (datetime) or null | When the request entered this step; `null` for `pending` and `skipped` |
| `description` | string or null | Dashboard sentence for this step |
| `checkpoints` | array\[object] | Individual attempts within the step, e.g. calls: `{ "text": string, "occurred_at": datetime }` |
| `action_request` | object or null | On `action_required` steps: `{ "id", "status": "awaiting_response" \| "answered" \| "resolved", "description", "response_text", "responded_at", "has_attachment" }` |

## PendingActionRequest

The open action request on a [RetrievalRequest](#retrievalrequest), returned by `GET /v2/retrieval-requests/{id}` only. `null` when nothing is waiting on your firm. Answer it with [Respond to action request](/api-reference/v2/endpoint/retrieval-requests/respond-to-action-request).

| Field | Type | Description |
| - | - | - |
| `id` | string | Action request identifier; matches the `id` of the current timeline entry's `action_request` |
| `description` | string | What Tavrn needs from your firm |
| `document` | object or null | File Tavrn attached to the action request (for example a provider invoice or letter): `{ "file_name", "file_size", "file_type", "download_url", "expires_in" }`. `download_url` is presigned and expires after `expires_in` seconds. `null` when there is no file |

## RequestedRecord

A single record line on a retrieval request. Each line targets one record type, optionally with its own date range and (for billing types) a deliverable format. A request may include multiple lines of the same `type` with different dates or formats.

| Field | Type | Required | Description |
| - | - | - | - |
| `type` | string (enum) | Yes | One of the record types listed below |
| `custom_label` | string | When `type` starts with `custom_` | Free-text label, e.g. `"Operative notes from Dr. Smith only"` |
| `deliverable_format` | string (enum) | When `type` is in the billing category | `itemized`, `account_balance`, or `insurance_claim_form` |
| `service_start_date` | string (date) or null | No | Overrides the request-level default with `YYYY-MM-DD`; omitted or `null` inherits the default |
| `service_end_date` | string (date) or null | No | Overrides the request-level default. `YYYY-MM-DD`, or `null` for ongoing / "Present" |
| `requirements` | array\[string] | No | Per-line documentation requirements: `certification` or `affidavit` (one kind per request — see note below). See [Permission-gated features](#permission-gated-features) below |

The table describes values accepted when creating a retrieval. GET and list
responses can contain additional `type`, `deliverable_format`, or `requirements`
strings; clients should handle unfamiliar values.

### `type` values

Grouped by category. The same categories appear in the dashboard form.

**Medical**

| `type` | Label | Description |
| - | - | - |
| `medical_records` | Medical Records | Complete copy of the patient's medical record |
| `medical_records_er` | ER Records | Records limited to emergency department visits |
| `medical_records_mental_health` | Mental Health Records | Patient's mental health records |
| `abstract_medical_records` | Abstract Records Only | Summary / abstract only (not the full record). **Permission-gated** — see below |
| `radiology_reports` | Radiology Reports | Written reports only — not the image files |
| `rfc` | Residual Functional Capacity | Treating-provider-completed RFC form (attached to the request as an `attachment`). **Permission-gated** — see below |
| `custom_medical` | Other (medical) | Use `custom_label` to specify |

**Billing** — `deliverable_format` is required for every billing line.

| `type` | Label |
| - | - |
| `billings` | All billing (umbrella) |
| `billing_physician` | Physician Billing |
| `billing_institutional` | Hospital Institutional Billing |
| `billing_er` | ER Physician Billing |
| `billing_radiology` | Radiology Billing |
| `billing_anesthesiology` | Anesthesia Billing |
| `billing_ambulance` | Ambulance Billing |
| `custom_billing` | Other (billing) — use `custom_label` |

**Imaging**

| `type` | Label | Description |
| - | - | - |
| `imaging` | Radiology Images | Image files only — not the written reports (use `radiology_reports` for those) |
| `custom_imaging` | Other (imaging) | Use `custom_label` to specify |

### `deliverable_format` values

Only applicable to billing-category lines.

| Value | Description |
| - | - |
| `itemized` | Line-item charges for each service rendered |
| `account_balance` | Summary of the patient's account balance including any payments applied |
| `insurance_claim_form` | Completed CMS-1500 with supporting clinical documentation and EOBs |

To request multiple formats for the same billing type, submit multiple lines:

```json theme={null}
[
  { "type": "billing_physician", "deliverable_format": "itemized" },
  { "type": "billing_physician", "deliverable_format": "account_balance" }
]
```

### Permission-gated features

A handful of values are available only when enabled for your organization. Submitting one your organization does not have access to is rejected by the API. Contact Tavrn support to enable for your organization.

| Surface | Value |
| - | - |
| `RequestedRecord.requirements` | `certification` |
| `RequestedRecord.requirements` | `affidavit` |
| `RequestedRecord.type` | `rfc` |
| `RequestedRecord.type` | `abstract_medical_records` |

Lines without `requirements` and without these gated `type` values work for all organizations.

A single request may use only one attestation kind — `certification` or `affidavit` — across all of its `requested_records`. Lines may include or omit `requirements`, but every line that includes one must use the same kind. A request that mixes the two (on the same line or different lines) is rejected with a `400 validation_error`:

```
requested_records cannot include both "affidavit" and "certification" requirements; choose one attestation per request
```

## Patient

Sub-object on a [RetrievalRequest](#retrievalrequest). Supply as much as you know — many facilities verify identity against DOB, SSN last-4, or address before releasing records.

| Field | Type | Required on create | Description |
| - | - | - | - |
| `name` | string | Yes | Patient full legal name |
| `date_of_birth` | string (date) | No | YYYY-MM-DD. Strongly recommended — most facilities require it to match records |
| `address` | string | No | Mailing address. Many facilities verify against this |
| `phone` | string | No | Phone number. Some facilities use this for verification or follow-up |
| `email` | string (email) | No | Email. Used by some facilities for verification or to send a portal invite |
| `gender` | string | No | Required by some facilities for identity verification |
| `ssn` | string | No | Social Security Number. Many facilities require the last 4 digits for identity verification |

GET and list always include the patient fields, but `name` and optional fields
can be `null` when unavailable. The API returns `ssn: null` even when an SSN was
supplied.

## Facility

The facility / provider being asked for records. To create a retrieval, supply this
object or a top-level `facility_id` from [facility search](#facility-search-result).
Required-on-create fields apply only when supplying the `facility` object.

| Field | Type | Required on create | Description |
| - | - | - | - |
| `name` | string | Yes | Facility / provider organization name |
| `address_line1` | string | Yes | Street address |
| `address_line2` | string | No | Suite, floor, etc. |
| `city` | string | Yes | City |
| `state` | string | Yes | US state code (2 letters) |
| `zip_code` | string | Yes | ZIP code |
| `phone` | string | No | Phone number (recommended) |
| `fax` | string | No | Fax number (recommended) |

GET and list always include the name and address fields, but any can be `null`
when unavailable. `phone` and `fax` can be omitted.

## Facility Search Result

Returned by [`GET /v2/facilities`](/api-reference/v2/endpoint/facilities/search-facilities)
in a `results` array, without pagination or a total count.

| Field | Type | Description |
| - | - | - |
| `id` | string | Facility ID to pass as `facility_id` when creating a retrieval |
| `name` | string | Facility name |
| `requirements` | array\[object] | Requirements for requesting records; empty when none are listed |

Each requirement has `slug` (identifier), `label`, `description` (string or null),
`category` (`input`, `document`, or `instruction`), and `record_types` (array of
categories such as `medical_records`, `billings`, or `radiology`). Empty
`record_types` means the requirement applies to all record types.
Document requirements may also include `template_download_url` (string, URI) for
an available blank template. Links are valid for 1 hour; repeat the facility search
for a fresh link. The field is omitted when no link is available.

## UploadedFile

Reference to a file uploaded via the [case presigned upload URL](/api-reference/v2/endpoint/cases/sign-upload) or, before a case exists, the [retrieval upload URL](/api-reference/v2/endpoint/retrieval-requests/sign-upload). Use the returned `upload_id` to attach it to a retrieval request.

| Field | Type | Required | Description |
| - | - | - | - |
| `upload_id` | string | Yes | Opaque upload identifier returned by sign-upload |
| `file_name` | string | Yes | Original file name |

Used directly as the element shape of `attachments[]`. The `auth_form` field uses an extended shape — [AuthFormUpload](#authformupload) — that adds optional signer metadata.

## AuthFormUpload

Extends [UploadedFile](#uploadedfile) with optional signer metadata. Used for the `auth_form` field on a retrieval request.

| Field | Type | Required | Description |
| - | - | - | - |
| `upload_id` | string | Yes | Opaque upload identifier returned by sign-upload |
| `file_name` | string | Yes | Original file name |
| `signer_name` | string | No | Full name of the person who signed the authorization, if not the patient (e.g., parent of a minor, legal guardian, POA). Omit when the patient signed |
| `signer_relationship` | string | No | Relationship of the signer to the patient (free text — e.g., `Parent`, `Legal Guardian`, `POA`). Only meaningful when `signer_name` is set |

When both `signer_name` and `signer_relationship` are omitted, the authorization is treated as signed by the patient themselves.

## RetrievalRequestDocument

Represents a record received from a facility, a provider invoice, or a request cost summary. Distinct from [Document](#document), which represents a file uploaded to a case for another workflow. The two resources do not overlap.

| Field | Type | Required | Description |
| - | - | - | - |
| `id` | string | Yes (read-only) | Opaque document identifier. For an invoice, it matches the ID in webhook `invoice_ids`. The request cost PDF uses `cost_summary` |
| `retrieval_request_id` | string | Yes | Associated retrieval request ID |
| `category` | string (enum) | Yes | `records`, `invoice`, or `cost_summary` |
| `record_types` | array\[string] | Yes | Content categories, commonly `medical_records`, `billings`, `radiology`, `abstract_records`, or `other`. Other values can appear. Empty for `invoice` and `cost_summary`. This is separate from [RequestedRecord](#requestedrecord) `type` |
| `metadata.provider_fee_amount` | number | Invoice only | Provider invoice amount in USD, not cents. Contributes to `costs.provider_fees`; `0` is valid. Records and cost summaries omit `metadata` |
| `file_name` | string or null | Yes | File name when available |
| `file_size` | integer or null | Yes | File size in bytes when known |
| `file_type` | string or null | Yes | MIME type when available |
| `page_count` | integer or null | Yes | Page count when known |
| `created_at` | string (datetime) or null | Yes (read-only) | Creation timestamp when known |

An invoice can appear in the document list and contribute to costs before it is
downloadable. Its download endpoint returns `404` until the file is available.
`retrieval_request.documents_available` is sent when it becomes downloadable.

A `cost_summary` is available once the request is completed and billing is finalized.
It summarizes Tavrn credits and fees, provider fees, and the total.
See [Request cost PDF](/guides/v2/retrieval-guide#request-cost-pdf) for the download flow.

### Enumerations

**category**:

* `records` — Records received from the facility (e.g., medical records, billing, radiology)
* `invoice` — A provider invoice for fees charged to retrieve the records
* `cost_summary` — A PDF of credits, provider fees, and total costs for a completed request with finalized billing

## Webhook

Represents a webhook endpoint configuration.

Creating a webhook requires `name`, `url`, and at least one event in `events`. `description` is optional. The table describes the object returned by GET, list, and update; the create response is shorter.

| Field | Type | In read response | Description |
| - | - | - | - |
| `id` | string | Yes | Opaque webhook identifier |
| `name` | string | Yes | Name unique within your organization |
| `url` | string (uri) | Yes | Webhook endpoint URL (must use HTTP/HTTPS) |
| `events` | array\[string] | Yes | Selected event types; new and updated webhooks require at least one |
| `description` | string or null | Yes | Optional webhook description |
| `is_enabled` | boolean | Yes | Whether webhook is enabled |
| `consecutive_failures` | integer | Yes | Count of consecutive events that failed after all delivery attempts |
| `last_failure_at` | string (datetime) or null | Yes | Last event that failed after all delivery attempts |
| `last_success_at` | string (datetime) or null | Yes | Last successful event delivery |
| `auto_disabled_at` | string (datetime) or null | Yes | When Tavrn disabled the webhook after five consecutive failed events |
| `last_failure` | object or null | Yes | Most recent non-test failed attempt: `at`, `status_code`, `error`, `event_type` |
| `secret_hint` | string | Yes | Last 4 chars of secret (for identification) |
| `created_by` | string | Yes | User or API key that created the webhook |
| `created_at` | string (datetime) | Yes | Creation timestamp |
| `updated_at` | string (datetime) | Yes | Last update timestamp |

### Webhook Events

* `retrieval_request.status_changed` - Public retrieval status or timeline changed
* `retrieval_request.action_required` - Client action request opened or reopened
* `retrieval_request.documents_available` - Records or a downloadable provider invoice became available

<Note>
  The `secret` field is returned only during webhook creation. The create response
  contains `id`, `name`, `url`, `description`, `events`, `secret`, `is_enabled`,
  `auto_disabled_at`, `last_failure`, and `created_at`. Read the webhook to get the
  additional health fields. API keys need `retrievals:read` as well as
  `webhooks:write` to subscribe to retrieval events.
</Note>

## Pagination

Cursor-paginated list endpoints, including cases, Requestors, and retrieval requests, use the fields below. `GET /v2/retrieval-requests/{id}/documents` returns the complete current document list in one response: `next` and `previous` are always `null`, and it does not accept `limit`, `cursor`, or `category` filters.

| Field | Type | Required | Description |
| - | - | - | - |
| `results` | array | Yes | Array of resource objects |
| `next` | string (uri) | Yes | URL to next page (null if no more pages) |
| `previous` | string (uri) | Yes | URL to previous page (null if first page) |

**Query Parameters for cursor-paginated lists**:

* `limit` - Max results per page (default: 20, max: 100)
* `cursor` - Opaque pagination cursor

## Error

Error response format.

| Field | Type | Required | Description |
| - | - | - | - |
| `error.code` | string | Yes | Machine-readable error code |
| `error.message` | string | Yes | Human-readable error message |

### Common Error Codes

* `invalid_api_key` - Missing or invalid API key
* `insufficient_scope` - API key lacks required scope
* `validation_error` - Request validation failed
* `resource_not_found` - Resource not found
* `invalid_request` - Malformed request
* `duplicate_name` - Webhook name already exists within your organization

## Example Objects

### Complete Case

```json theme={null}
{
  "id": "case_abc123",
  "case_number": "EI-2025-0001",
  "title": "Jane Doe v. ACME Corp",
  "client_name": "Jane Doe",
  "description": "Rear-end MVA with cervical injury",
  "client_date_of_birth": "1989-04-12",
  "client_address": "123 Main St, Austin, TX 78701",
  "client_phone": "+1-512-555-0101",
  "client_email": "jane@example.com",
  "date_of_injury": "2025-01-10",
  "deposition_date": "2025-06-15",
  "case_category": "motor_vehicle_accident",
  "status": "active",
  "external_id": "expert-institute-12345",
  "created_at": "2025-02-01T12:34:56Z",
  "updated_at": "2025-02-01T12:34:56Z"
}
```

### Paginated Response

```json theme={null}
{
  "results": [
    { "id": "case_1", "..." : "..." },
    { "id": "case_2", "..." : "..." }
  ],
  "next": "https://enterprise.tavrn.ai/v2/cases?limit=20&cursor=next_cursor",
  "previous": null
}
```

### Retrieval Request Creation (case-scoped)

This is a body for `POST /v2/cases/{case_id}/retrieval-requests`. The standalone
`POST /v2/retrieval-requests` route also needs either `case_id` or an inline `case`.

```json theme={null}
{
  "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",
      "requirements": ["certification"]
    },
    {
      "type": "billings",
      "deliverable_format": "itemized"
    },
    {
      "type": "billing_radiology",
      "deliverable_format": "account_balance",
      "service_start_date": "2022-01-01",
      "service_end_date": "2022-12-31"
    },
    {
      "type": "custom_medical",
      "custom_label": "Operative notes from Dr. Smith only"
    }
  ],
  "auth_form": {
    "upload_id": "11111111-1111-4111-8111-111111111111",
    "file_name": "jane_doe_hipaa.pdf"
  },
  "attachments": [
    {
      "upload_id": "22222222-2222-4222-8222-222222222222",
      "file_name": "cover_letter.pdf"
    }
  ]
}
```

### Retrieval Request GET Response (abridged)

This separate example shows an existing request with two record lines and
patient contact details already on file.

```json theme={null}
{
  "id": "rr_abc123",
  "order_number": "T-ABC-12345",
  "case_id": "case_abc123",
  "requestor_id": "111111111111111111111111",
  "platform_url": "https://platform.tavrn.ai/cases/case_abc123?section=workflows%2Fretrieval-manager&view=detail&orderId=rr_abc123",
  "status": "processing",
  "action_required_reason": null,
  "stage": "request_sent",
  "stage_label": "Correspondence Sent",
  "stage_description": "We've sent out your request via fax and will be following up with the provider to check in on progress.",
  "patient": {
    "name": "Jane Doe",
    "date_of_birth": "1989-04-12",
    "address": "123 Main St, Austin, TX 78701",
    "phone": "+1-512-555-0101",
    "email": "jane@example.com",
    "gender": null,
    "ssn": null
  },
  "facility": {
    "name": "Example General Hospital",
    "address_line1": "100 Example Ave",
    "address_line2": null,
    "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",
      "service_start_date": "2024-03-15",
      "service_end_date": "2024-09-30",
      "requirements": ["certification"]
    },
    {
      "type": "billings",
      "deliverable_format": "itemized",
      "service_start_date": "2024-03-15",
      "service_end_date": "2024-09-30",
      "requirements": []
    }
  ],
  "notes": null,
  "documents_summary": {
    "records_count": 0,
    "invoices_count": 0
  },
  "documents": [],
  "costs": {
    "tavrn_credits_consumed": 1,
    "tavrn_fee": 35,
    "provider_fees": 0,
    "total_cost": 35
  },
  "created_at": "2025-02-01T12:50:00Z",
  "updated_at": "2025-02-03T09:14:21Z",
  "public_updated_at": "2025-02-03T09:14:21Z",
  "completed_at": null
}
```

## Next Steps

* [Create a case](/api-reference/v2/endpoint/cases/create-case)
* [Upload documents](/guides/v2/document-upload-guide)
* [Create a retrieval request](/api-reference/v2/endpoint/retrieval-requests/create-retrieval-request)
* [Record Retrieval Guide](/guides/v2/retrieval-guide)