Skip to main content

​
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 after onboarding. If your organization does not have access yet, book a demo.

​
Get started in four steps

1

Get access and an API key

An organization admin creates a key in the Tavrn Platform and picks its scopes. Account →
2

Set up your firm profile

Firm name, letter of representation, provider invoice approval limit, affidavit preferences. Firm setup →
3

Create your first retrieval

One call creates the case, picks the profile, and sends the request to the provider. First retrieval →
4

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 →

​
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:
See Authentication for more details.

​
Base URL

All API requests should be made to: https://enterprise.tavrn.ai/v2

​
Common Response Format

All API endpoints return JSON responses with consistent formatting:

​
Success Response

​
Error Response

See Errors for more details.

​
Pagination

List endpoints return cursor-based pagination:

​
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
  3. Create a Retrieval Request: Submit a request with the patient, facility, records and authorization
  4. Set Up Webhooks: Configure webhook endpoints to receive status updates
  5. Download Records and Invoices: Fetch released records and provider invoices 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.

​
Next Steps

​
Support

Need help? Contact our support team: