# Tavrn Enterprise API

> Tavrn's Enterprise API: request a patient's medical records from any US provider, track retrieval with webhooks, and download the records and provider invoices.

- [Overview](https://docs.tavrn.ai/guides/v2/overview.md): Request medical records from any US provider, track retrieval with webhooks, and download the records and provider invoices
- [1. Account and API key](https://docs.tavrn.ai/guides/v2/get-started/account.md): Get access to the Tavrn Platform and create an API key with the scopes your integration needs.
- [2. Firm setup](https://docs.tavrn.ai/guides/v2/get-started/firm-setup.md): Create the Requestor profile Tavrn uses on every request: firm name, letter of representation, provider invoice approval limit, and affidavits.
- [3. First retrieval](https://docs.tavrn.ai/guides/v2/get-started/first-retrieval.md): Upload the signed authorization and create a case and retrieval request in one call.
- [4. Track and download](https://docs.tavrn.ai/guides/v2/get-started/track-and-download.md): Follow a request with webhooks and incremental polling, answer action requests through the API, and download records and provider invoices with their amounts.
- [Record Retrieval Guide](https://docs.tavrn.ai/guides/v2/retrieval-guide.md): Submit medical record retrieval requests, track them with webhooks, and download available records and provider invoices
- [Webhooks](https://docs.tavrn.ai/guides/v2/webhooks.md): Real-time event notifications for retrieval requests
- [Authentication](https://docs.tavrn.ai/guides/v2/authentication.md): API key authentication for Enterprise API v2
- [Data Models & Schemas](https://docs.tavrn.ai/guides/v2/schemas.md): Complete data model documentation for Enterprise API v2
- [Errors](https://docs.tavrn.ai/guides/v2/errors.md): Error handling and API error codes
- [API Status](https://docs.tavrn.ai/api-status.md)
- [Document Upload Guide](https://docs.tavrn.ai/guides/v2/document-upload-guide.md): Complete guide to the 3-step document upload workflow
- [Create a case](https://docs.tavrn.ai/api-reference/v2/endpoint/cases/create-case.md): Create a new legal case
- [List cases](https://docs.tavrn.ai/api-reference/v2/endpoint/cases/list-cases.md): List all cases with cursor-based pagination
- [Get case by ID](https://docs.tavrn.ai/api-reference/v2/endpoint/cases/get-case.md): Retrieve a specific case by its ID
- [Update case](https://docs.tavrn.ai/api-reference/v2/endpoint/cases/update-case.md): Update case fields (partial update)
- [Request presigned upload URL](https://docs.tavrn.ai/api-reference/v2/endpoint/cases/sign-upload.md): Request a presigned URL for uploading a file under a case. The returned `upload_id` can be used to [create a case document](/api-reference/v2/endpoint/documents/create-document) or to attach a file as `auth_form` or in `attachments[]` when [creating a retrieval request](/api-reference/v2/endpoint/re…
- [Create document record](https://docs.tavrn.ai/api-reference/v2/endpoint/documents/create-document.md): Create a document record after uploading the file via the presigned URL
- [List all documents](https://docs.tavrn.ai/api-reference/v2/endpoint/documents/list-documents.md): List all documents across cases
- [Get document by ID](https://docs.tavrn.ai/api-reference/v2/endpoint/documents/get-document.md): Retrieve a specific document by its ID
- [Download document](https://docs.tavrn.ai/api-reference/v2/endpoint/documents/download-document.md): Get a presigned download URL for a document (valid for 1 hour)
- [Update document](https://docs.tavrn.ai/api-reference/v2/endpoint/documents/update-document.md): Update document metadata or archive status
- [Request presigned upload URL (deprecated)](https://docs.tavrn.ai/api-reference/v2/endpoint/documents/sign-upload.md): **Deprecated.** Use [`POST /v2/cases/{case_id}/sign-upload`](/api-reference/v2/endpoint/cases/sign-upload) instead. Request and response shapes are the same.
- [Create Requestor](https://docs.tavrn.ai/api-reference/v2/endpoint/requestors/create-requestor.md): Create a retrieval profile. Requires requestors:write. Unspecified documents, affidavits, and correspondence start empty; an unspecified invoice limit uses $100. The default profile is unchanged. Each successful POST creates an additional profile. Retain its ID for reuse.
- [List Requestors](https://docs.tavrn.ai/api-reference/v2/endpoint/requestors/list-requestors.md): List your organization's Requestor profiles. is_default identifies the default profile. Requires requestors:read.
- [Get Requestor](https://docs.tavrn.ai/api-reference/v2/endpoint/requestors/get-requestor.md): Read a Requestor profile. Requires requestors:read. An unavailable ID returns 404.
- [Update Requestor](https://docs.tavrn.ai/api-reference/v2/endpoint/requestors/update-requestor.md): Update this profile, including the default when addressed by ID. Requires requestors:write. Omitted fields remain unchanged; null clears nullable settings; supplied affidavit arrays replace their collections. Updates apply to linked retrievals. The API does not delete profiles, switch the default, o…
- [Get Requestor document upload URL](https://docs.tavrn.ai/api-reference/v2/endpoint/requestors/sign-upload.md): Returns a temporary upload_url and upload_id for a Requestor document. PUT a readable, unencrypted PDF (.pdf, application/pdf, at most 25 MiB) to upload_url, then use upload_id in a Requestor create or update body. Requires requestors:write. Upload within 15 minutes and use upload_id within one hour…
- [Search facilities](https://docs.tavrn.ai/api-reference/v2/endpoint/facilities/search-facilities.md): Search by facility name, alias, phone, fax, address, or NPI. Requires retrievals:read. Use a result's id as facility_id when creating a retrieval request.
- [Create retrieval with case and Requestor](https://docs.tavrn.ai/api-reference/v2/endpoint/retrieval-requests/create-with-case-and-requestor.md): Create a retrieval using patient and requested_records, plus exactly one of facility_id from GET /v2/facilities or a manual facility object. Provide either case_id or an inline case. Use requestor_id for an existing profile, an inline requestor to create one, or neither to use the organization defau…
- [Get retrieval file upload URL](https://docs.tavrn.ai/api-reference/v2/endpoint/retrieval-requests/sign-upload.md): Returns a temporary upload_url and upload_id for a retrieval authorization or attachment, including before a case exists. PUT the file to upload_url, then use upload_id in auth_form or attachments when creating a retrieval. Requires retrievals:write. Upload within 15 minutes and use upload_id within…
- [Create retrieval request](https://docs.tavrn.ai/api-reference/v2/endpoint/retrieval-requests/create-retrieval-request.md): Create a retrieval under the case in the URL using patient and requested_records, plus exactly one of facility_id from GET /v2/facilities or a manual facility object. An inline case is not accepted. Optionally select requestor_id or create an inline requestor; omitting both uses the default profile.…
- [List retrieval requests](https://docs.tavrn.ai/api-reference/v2/endpoint/retrieval-requests/list-retrieval-requests.md): List your organization's retrieval requests. Use public_updated_since and include=details for incremental reconciliation. Follow next URLs unchanged, including after an empty page, and save next_public_updated_since only after processing the final page. This returns current state, not an event histo…
- [Get retrieval request](https://docs.tavrn.ai/api-reference/v2/endpoint/retrieval-requests/get-retrieval-request.md): Retrieve current request details, including status, timeline, pending client action, documents, public_updated_at, and costs. Fetch details after an IDs-only webhook or to refresh costs; use incremental list polling for organization-wide reconciliation.
- [Cancel retrieval request](https://docs.tavrn.ai/api-reference/v2/endpoint/retrieval-requests/cancel-retrieval-request.md): Cancel a retrieval request. Cancellation is final and only allowed while the request is non-terminal.
- [Respond to action request](https://docs.tavrn.ai/api-reference/v2/endpoint/retrieval-requests/respond-to-action-request.md): Answer the retrieval request's open client action request (the request is `action_required` and `pending_action_request` is set). A request has at most one open action request at a time; this endpoint always answers that one. Send a text `message`, and optionally attach one file uploaded with [Reque…
- [Send support message](https://docs.tavrn.ai/api-reference/v2/endpoint/retrieval-requests/send-support-message.md): Send a support message. Messages and published replies are logged without changing retrieval status. Requires retrievals:write. Linked CMS connections must have support messaging enabled. See [Support messages](/guides/v2/retrieval-guide#support-messages).
- [List retrieval documents](https://docs.tavrn.ai/api-reference/v2/endpoint/retrieval-requests/list-retrieval-documents.md): List records, provider invoices, and available request cost summaries in one response. This endpoint does not accept pagination or category filters. An invoice can appear before it is downloadable; retrieval_request.documents_available is sent when its file becomes available.
- [Download retrieval document](https://docs.tavrn.ai/api-reference/v2/endpoint/retrieval-requests/download-retrieval-document.md): Get a short-lived download URL for a retrieval document. Use document_id cost_summary for the request cost PDF, available once the request is completed and billing is finalized. Returns 404 when the document is unavailable.
- [Create webhook](https://docs.tavrn.ai/api-reference/v2/endpoint/webhooks/create-webhook.md): Register a new webhook endpoint. Requires `webhooks:write`; subscribing to retrieval events also requires `retrievals:read`. The secret is returned only in this response.
- [List webhooks](https://docs.tavrn.ai/api-reference/v2/endpoint/webhooks/list-webhooks.md): List all webhooks for the organization. Requires `webhooks:read`; secrets are not returned.
- [Get webhook by ID](https://docs.tavrn.ai/api-reference/v2/endpoint/webhooks/get-webhook.md): Retrieve a specific webhook by its ID. Requires `webhooks:read`; the secret is not returned.
- [Update webhook](https://docs.tavrn.ai/api-reference/v2/endpoint/webhooks/update-webhook.md): Update webhook configuration. Requires `webhooks:write`; setting retrieval events or re-enabling a retrieval subscription also requires `retrievals:read`. Re-enabling clears `auto_disabled_at` and resets `consecutive_failures`.
- [Send test event](https://docs.tavrn.ai/api-reference/v2/endpoint/webhooks/test-webhook.md): Send one signed webhook.test event to the webhook URL and return the result. Requires webhooks:write. No request body. HTTP 200 means the test was attempted; inspect success for the delivery outcome. Failed tests are not retried. Tests work on disabled webhooks and do not change webhook health field…
- [Delete webhook](https://docs.tavrn.ai/api-reference/v2/endpoint/webhooks/delete-webhook.md): Delete a webhook endpoint. Requires `webhooks:write`.
- [Support](https://docs.tavrn.ai/support.md)

## OpenAPI Specs

- [openapi](/api-reference/v2/openapi.json)