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

# Overview

> Request medical records from any US provider, track retrieval with webhooks, and download the records and provider invoices

## Overview

Tavrn retrieves medical records on behalf of healthcare organizations, health-tech and AI companies, and law firms: one signed patient authorization in, the complete record out. The Enterprise API v2 lets your systems do this programmatically: create cases, submit record retrieval requests to any US provider, track each request through its lifecycle with webhooks and incremental polling, respond to action requests, and download the retrieved records and provider invoices.

Access is per organization: API keys are created by an organization admin in the [Tavrn Platform](https://platform.tavrn.ai/dashboard/api) after onboarding. If your organization does not have access yet, [book a demo](https://www.tavrn.ai/demo).

## Get started in four steps

<Steps>
  <Step title="Get access and an API key">
    An organization admin creates a key in the Tavrn Platform and picks its scopes. [Account →](/guides/v2/get-started/account)
  </Step>

  <Step title="Set up your firm profile">
    Firm name, letter of representation, provider invoice approval limit, affidavit preferences. [Firm setup →](/guides/v2/get-started/firm-setup)
  </Step>

  <Step title="Create your first retrieval">
    One call creates the case, picks the profile, and sends the request to the provider. [First retrieval →](/guides/v2/get-started/first-retrieval)
  </Step>

  <Step title="Track it and download records and invoices">
    Webhooks plus incremental polling, action requests answered through the API, records and provider invoices with amounts. [Track and download →](/guides/v2/get-started/track-and-download)
  </Step>
</Steps>

## Key Features

### Record Retrieval

* **Submit requests**: Send patient, facility, record, and authorization details using an existing case or create a case in the same request
* **Choose a Requestor**: Use your organization's default profile, select another profile, or create one inline
* **Track changes**: Receive retrieval webhooks and use incremental polling to reconcile missed updates
* **Receive records and invoices**: Download released records and approved provider invoices; check current request costs

### Case Management

* **Create Cases**: Group requests by patient or matter with client and case information
* **Track Progress**: Monitor case status and organization
* **Update Cases**: Modify case details and metadata
* **External Mapping**: Link cases to your system via external IDs

### Document Handling

* **Direct uploads**: Upload files via short-lived presigned URLs
* **Document library**: Organize documents with virtual paths and metadata
* **Download access**: Time-limited download URLs
* **Archive management**: Archive and unarchive documents as needed

### Webhooks

* **Status Tracking**: Real-time retrieval status updates with webhooks
* **Secure webhooks**: HMAC-signed webhook payloads with automatic retries

## Authentication

All Enterprise API endpoints use API key authentication. Include your API key in the Authorization header:

```http theme={null}
Authorization: Bearer tavrn_sk_live_...
```

See [Authentication](/guides/v2/authentication) for more details.

## Base URL

All API requests should be made to:

<code>[https://enterprise.tavrn.ai/v2](https://enterprise.tavrn.ai/v2)</code>

## Common Response Format

All API endpoints return JSON responses with consistent formatting:

### Success Response

```json theme={null}
{
  "id": "case_abc123",
  "title": "Jane Doe v. ACME Corp",
  "client_name": "Jane Doe",
  "status": "active",
  "created_at": "2025-02-01T12:34:56Z",
  "updated_at": "2025-02-01T12:34:56Z"
}
```

### Error Response

See [Errors](/guides/v2/errors) for more details.

### Pagination

List endpoints return cursor-based pagination:

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

## Getting Started

1. **Create an API Key**: Generate an API key from your organization dashboard
2. **Set up your firm profile**: Add your [letter of representation and invoice preferences](/guides/v2/get-started/firm-setup)
3. **Create a Retrieval Request**: [Submit a request](/guides/v2/get-started/first-retrieval) with the patient, facility, records and authorization
4. **Set Up Webhooks**: Configure [webhook endpoints](/guides/v2/webhooks) to receive status updates
5. **Download Records and Invoices**: [Fetch released records and provider invoices](/guides/v2/get-started/track-and-download) when they become available

## API Conventions

### Field Naming

* All JSON field names use `snake_case` (e.g., `client_name`, `created_at`)
* Timestamps are ISO 8601 format (e.g., `2025-02-01T12:34:56Z`)

### Pagination

* Default limit: 20 results
* Maximum limit: 100 results
* Cursor-based pagination via `next` and `previous` URLs
* For retrieval change reconciliation, follow `next` through the final page and save its `next_public_updated_since` checkpoint. See the [Record Retrieval Guide](/guides/v2/retrieval-guide#incremental-polling).

## Next Steps

* [Get started](/guides/v2/get-started/account) - Account, firm profile, first retrieval, download
* [Authentication](/guides/v2/authentication) - API key setup and scopes
* [Data Models & Schemas](/guides/v2/schemas) - Understand the data structures
* [Create a Case](/api-reference/v2/endpoint/cases/create-case) - Your first API call
* [Document Upload Guide](/guides/v2/document-upload-guide) - Upload workflow
* [Record Retrieval Guide](/guides/v2/retrieval-guide) - Retrieve records and manage Requestor profiles
* [Webhooks](/guides/v2/webhooks) - Set up real-time notifications

## Support

Need help? Contact our support team:

* Email: [contact@tavrn.ai](mailto:contact@tavrn.ai)