Data Models & Schemas

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 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]	Get or `include=details` (read-only)	Ordered lifecycle steps as rendered on the dashboard. Omitted from ordinary list results
`pending_action_request`	object (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)	Yes	Patient details
`facility`	object (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. Provide exactly one of `facility_id` or `facility`
`requested_records`	array[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)	Yes (on create)	The signed HIPAA authorization PDF, plus optional signer metadata if not signed by the patient
`attachments`	array[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]	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)	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 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 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 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, returned by GET /v2/retrieval-requests/{id} only. null when nothing is waiting on your firm. Answer it with 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 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:

[
  { "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. 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. 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 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 or, before a case exists, the retrieval upload URL. 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 — that adds optional signer metadata.

AuthFormUpload

Extends 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, 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 `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 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

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.

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

{
  "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

{
  "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.

{
  "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.

{
  "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
}

Get started

Retrieval reference

Case documents

Overview

Case

Enumerations

Document

RetrievalRequest

Enumerations

RetrievalRequestCosts

RetrievalTimelineEntry

PendingActionRequest

RequestedRecord

`type` values

`deliverable_format` values

Permission-gated features

Patient

Facility

Facility Search Result

UploadedFile

AuthFormUpload

RetrievalRequestDocument

Enumerations

Webhook

Webhook Events

Error

Common Error Codes

Example Objects

Complete Case

Paginated Response

Retrieval Request Creation (case-scoped)

Retrieval Request GET Response (abridged)

Next Steps

​Overview

​Case

​Enumerations

​Document

​RetrievalRequest

​Enumerations

​RetrievalRequestCosts

​RetrievalTimelineEntry

​PendingActionRequest

​RequestedRecord

​type values

​deliverable_format values

​Permission-gated features

​Patient

​Facility

​Facility Search Result

​UploadedFile

​AuthFormUpload

​RetrievalRequestDocument

​Enumerations

​Webhook

​Webhook Events

​Pagination

​Error

​Common Error Codes

​Example Objects

​Complete Case

​Paginated Response

​Retrieval Request Creation (case-scoped)

​Retrieval Request GET Response (abridged)

​Next Steps

Overview

Case

Enumerations

Document

RetrievalRequest

Enumerations

RetrievalRequestCosts

RetrievalTimelineEntry

PendingActionRequest

RequestedRecord

`type` values

`deliverable_format` values

Permission-gated features

Patient

Facility

Facility Search Result

UploadedFile

AuthFormUpload

RetrievalRequestDocument

Enumerations

Webhook

Webhook Events

Pagination

Error

Common Error Codes

Example Objects

Complete Case

Paginated Response

Retrieval Request Creation (case-scoped)

Retrieval Request GET Response (abridged)

Next Steps