{ "openapi": "3.0.1", "info": { "title": "Tavrn Platform API", "version": "1.0.0", "description": "Enterprise API for medical record retrieval: cases, retrieval requests, retrieved records and provider invoices, case documents, and webhook notifications.", "contact": { "name": "Tavrn Support", "email": "contact@tavrn.ai" } }, "servers": [ { "url": "https://enterprise.tavrn.ai", "description": "Production server" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "API key authentication. Use format: `Authorization: Bearer tavrn_sk_live_...`" } }, "schemas": { "Case": { "type": "object", "required": [ "id", "case_number", "title", "client_name", "status", "case_category", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "Unique case identifier", "example": "case_abc123" }, "case_number": { "type": "string", "description": "Auto-generated case number", "example": "EI-2025-0001" }, "title": { "type": "string", "description": "Case title", "example": "Jane Doe v. ACME Corp" }, "client_name": { "type": "string", "description": "Client's name", "example": "Jane Doe" }, "description": { "type": "string", "nullable": true, "description": "Case description", "example": "Rear-end MVA with cervical injury" }, "client_date_of_birth": { "type": "string", "format": "date", "nullable": true, "description": "Client's date of birth (YYYY-MM-DD)", "example": "1989-04-12" }, "client_address": { "type": "string", "nullable": true, "description": "Client's address", "example": "123 Main St, Austin, TX 78701" }, "client_phone": { "type": "string", "nullable": true, "description": "Client's phone number", "example": "+1-512-555-0101" }, "client_email": { "type": "string", "format": "email", "nullable": true, "description": "Client's email address", "example": "jane@example.com" }, "date_of_injury": { "type": "string", "format": "date", "nullable": true, "description": "Date of injury (YYYY-MM-DD)", "example": "2025-01-10" }, "deposition_date": { "type": "string", "format": "date", "nullable": true, "description": "Deposition date (YYYY-MM-DD)", "example": "2025-06-15" }, "case_category": { "type": "string", "enum": [ "personal_injury", "motor_vehicle_accident", "medical_malpractice", "workers_compensation", "product_liability", "premises_liability", "wrongful_death", "other" ], "description": "Case category", "example": "personal_injury" }, "status": { "type": "string", "enum": [ "active", "pending", "closed", "archived" ], "description": "Case status", "example": "active" }, "external_id": { "type": "string", "nullable": true, "description": "External identifier for client mapping", "example": "expert-institute-12345" }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp (ISO 8601)", "example": "2025-02-01T12:34:56Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp (ISO 8601)", "example": "2025-02-01T12:34:56Z" } } }, "CaseCreate": { "type": "object", "required": [ "title", "client_name" ], "properties": { "title": { "type": "string", "description": "Case title", "example": "Jane Doe v. ACME Corp", "maxLength": 500, "minLength": 1 }, "client_name": { "type": "string", "description": "Client's name", "example": "Jane Doe", "maxLength": 200, "minLength": 1 }, "description": { "type": "string", "description": "Case description", "maxLength": 5000 }, "client_date_of_birth": { "type": "string", "format": "date", "description": "Client's date of birth (YYYY-MM-DD)" }, "client_address": { "type": "string", "description": "Client's address", "maxLength": 500 }, "client_phone": { "type": "string", "description": "Client's phone number", "maxLength": 50 }, "client_email": { "type": "string", "format": "email", "description": "Client's email address" }, "date_of_injury": { "type": "string", "format": "date", "description": "Date of injury (YYYY-MM-DD, must be in the past)" }, "deposition_date": { "type": "string", "format": "date", "description": "Deposition date (YYYY-MM-DD)" }, "case_category": { "type": "string", "enum": [ "personal_injury", "motor_vehicle_accident", "medical_malpractice", "workers_compensation", "product_liability", "premises_liability", "wrongful_death", "other" ], "description": "Case category (defaults to personal_injury)", "default": "personal_injury" }, "status": { "type": "string", "enum": [ "active", "pending", "closed" ], "description": "Case status (defaults to active)", "default": "active" }, "external_id": { "type": "string", "description": "External identifier for client mapping", "maxLength": 255 } }, "additionalProperties": false }, "CaseUpdate": { "type": "object", "properties": { "title": { "type": "string", "description": "Case title" }, "description": { "type": "string", "nullable": true, "description": "Case description" }, "client_email": { "type": "string", "format": "email", "nullable": true, "description": "Client's email address" }, "status": { "type": "string", "enum": [ "active", "pending", "closed", "archived" ], "description": "Case status" }, "external_id": { "type": "string", "nullable": true, "description": "External identifier" } } }, "Document": { "type": "object", "required": [ "id", "case_id", "file_name", "file_size", "file_type", "archived", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "Unique document identifier", "example": "doc_abc123" }, "case_id": { "type": "string", "description": "Associated case ID", "example": "case_xyz" }, "file_name": { "type": "string", "description": "File name", "example": "medical_record.pdf" }, "file_size": { "type": "integer", "description": "File size in bytes", "example": 1234567 }, "file_type": { "type": "string", "description": "MIME type", "example": "application/pdf" }, "path": { "type": "string", "nullable": true, "description": "Virtual path for UI grouping", "example": "Example_General_Hospital" }, "archived": { "type": "boolean", "description": "Whether document is archived", "example": false }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp (ISO 8601)", "example": "2025-02-01T12:34:56Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp (ISO 8601)", "example": "2025-02-01T12:34:56Z" } } }, "SignUploadRequest": { "type": "object", "required": [ "file_name", "file_type" ], "properties": { "file_name": { "type": "string", "description": "File name", "example": "medical_record.pdf" }, "file_type": { "type": "string", "description": "MIME type", "example": "application/pdf" } } }, "SignUploadResponse": { "type": "object", "required": [ "upload_id", "upload_url", "expires_at" ], "properties": { "upload_id": { "type": "string", "format": "uuid", "description": "Temporary upload identifier. Consume within one hour of signing.", "example": "11111111-1111-4111-8111-111111111111" }, "upload_url": { "type": "string", "description": "Presigned PUT URL. Upload bytes within 15 minutes.", "example": "https://s3.amazonaws.com/..." }, "expires_at": { "type": "string", "format": "date-time", "description": "Upload identifier expiry, one hour after signing. The PUT URL expires after 15 minutes.", "example": "2025-02-01T13:34:56Z" } } }, "OrganizationSignUploadRequest": { "type": "object", "properties": { "file_name": { "type": "string", "minLength": 1, "maxLength": 500 }, "file_type": { "type": "string", "minLength": 1, "maxLength": 200, "example": "application/pdf" } }, "required": [ "file_name", "file_type" ] }, "OrganizationSignUploadResponse": { "type": "object", "required": [ "upload_id", "upload_url", "expires_at" ], "properties": { "upload_id": { "type": "string", "description": "Temporary upload identifier for this upload flow. Use within one hour.", "example": "11111111-1111-4111-8111-111111111111", "format": "uuid" }, "upload_url": { "type": "string", "description": "Presigned PUT URL. Upload bytes within 15 minutes using the same Content-Type.", "example": "https://upload-url.example.com/..." }, "expires_at": { "type": "string", "format": "date-time", "description": "Upload identifier expiry, one hour after signing. The PUT URL expires after 15 minutes.", "example": "2025-02-01T13:34:56Z" } } }, "DocumentCreate": { "type": "object", "required": [ "upload_id" ], "properties": { "upload_id": { "type": "string", "description": "Upload ID from sign-upload endpoint", "example": "11111111-1111-4111-8111-111111111111" }, "path": { "type": "string", "nullable": true, "description": "Virtual path for UI grouping", "example": "Example_General_Hospital" } } }, "DocumentUpdate": { "type": "object", "properties": { "path": { "type": "string", "nullable": true, "description": "Virtual path for UI grouping" }, "archived": { "type": "boolean", "description": "Archive or unarchive document" } } }, "DownloadResponse": { "type": "object", "required": [ "download_url", "expires_in" ], "properties": { "download_url": { "type": "string", "description": "Presigned download URL", "example": "https://s3.amazonaws.com/..." }, "expires_in": { "type": "integer", "description": "URL validity in seconds (3600 = 1 hour)", "example": 3600 } } }, "Webhook": { "type": "object", "required": [ "id", "name", "url", "description", "events", "is_enabled", "consecutive_failures", "last_failure_at", "last_success_at", "auto_disabled_at", "last_failure", "secret_hint", "created_by", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "Opaque webhook identifier.", "example": "507f1f77bcf86cd799439016" }, "name": { "type": "string", "description": "Webhook name, unique within your organization", "example": "Production webhook" }, "url": { "type": "string", "format": "uri", "description": "Webhook endpoint URL (must use HTTP/HTTPS)", "example": "https://client.example.com/webhooks/tavrn" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "retrieval_request.status_changed", "retrieval_request.action_required", "retrieval_request.documents_available" ] }, "description": "Subscribed event types. New and updated subscriptions require at least one event.", "example": [ "retrieval_request.status_changed", "retrieval_request.documents_available" ] }, "description": { "type": "string", "nullable": true, "description": "Optional webhook description", "example": "Production webhook for retrieval events" }, "is_enabled": { "type": "boolean", "description": "Whether webhook is enabled", "example": true }, "consecutive_failures": { "type": "integer", "description": "Count of consecutive events that failed after all delivery attempts", "example": 0 }, "last_failure_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Last event that failed after all delivery attempts (ISO 8601), or null" }, "last_success_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Last successful event delivery (ISO 8601), or null" }, "auto_disabled_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When Tavrn automatically disabled this webhook after 5 consecutive failed deliveries (ISO 8601), or null. Cleared when you set `is_enabled` to `true`." }, "last_failure": { "type": "object", "nullable": true, "description": "Most recent unsuccessful delivery attempt, or null. Test events are excluded.", "required": [ "at", "status_code", "error", "event_type" ], "properties": { "at": { "type": "string", "format": "date-time", "description": "When the attempt was made (ISO 8601)", "example": "2026-10-07T17:30:00.000Z" }, "status_code": { "type": "integer", "nullable": true, "description": "HTTP status returned by your endpoint, or null if no response was received", "example": 502 }, "error": { "type": "string", "nullable": true, "description": "Reason for the unsuccessful delivery attempt.", "example": "HTTP 502" }, "event_type": { "type": "string", "description": "Event type of the failed delivery", "example": "retrieval_request.status_changed" } } }, "secret_hint": { "type": "string", "description": "Last 4 characters of webhook secret (for identification)", "example": "...Ab12" }, "created_by": { "type": "string", "description": "User or API key that created the webhook" }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp (ISO 8601)", "example": "2025-02-01T12:34:56Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp (ISO 8601)", "example": "2025-02-01T12:34:56Z" } } }, "WebhookCreate": { "type": "object", "required": [ "name", "url", "events" ], "properties": { "name": { "type": "string", "minLength": 1, "description": "Webhook name, unique within your organization", "example": "Production webhook", "maxLength": 100 }, "url": { "type": "string", "format": "uri", "description": "Webhook endpoint URL (must use HTTP/HTTPS)", "example": "https://client.example.com/webhooks/tavrn", "maxLength": 2048 }, "events": { "type": "array", "items": { "type": "string", "enum": [ "retrieval_request.status_changed", "retrieval_request.action_required", "retrieval_request.documents_available" ] }, "minItems": 1, "description": "Event types to subscribe to (at least one required)", "example": [ "retrieval_request.status_changed", "retrieval_request.documents_available" ] }, "description": { "type": "string", "nullable": true, "description": "Optional webhook description", "example": "Production webhook for retrieval events", "maxLength": 500 } } }, "WebhookCreateResponse": { "type": "object", "description": "Creation response. Read or list the webhook for delivery health fields.", "required": [ "id", "name", "url", "description", "events", "secret", "is_enabled", "auto_disabled_at", "last_failure", "created_at" ], "properties": { "id": { "type": "string", "description": "Opaque webhook identifier.", "example": "507f1f77bcf86cd799439016" }, "name": { "type": "string", "description": "Webhook name, unique within your organization", "example": "Production webhook" }, "url": { "type": "string", "format": "uri", "example": "https://client.example.com/webhooks/tavrn" }, "description": { "type": "string", "nullable": true, "description": "Optional webhook description" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "retrieval_request.status_changed", "retrieval_request.action_required", "retrieval_request.documents_available" ] } }, "secret": { "type": "string", "description": "Webhook secret, returned only on creation. Store it securely.", "example": "whsec_XyZ789AbCdEfGhIjKlMnOpQrSt" }, "is_enabled": { "type": "boolean", "example": true }, "auto_disabled_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Always null when the webhook is created" }, "last_failure": { "type": "object", "nullable": true, "description": "Always null when the webhook is created" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-10-08T12:00:00.000Z" } } }, "WebhookUpdate": { "type": "object", "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "description": "Webhook name, unique within your organization", "example": "Production webhook", "maxLength": 100 }, "url": { "type": "string", "format": "uri", "description": "Webhook endpoint URL (must use HTTP/HTTPS)", "maxLength": 2048 }, "events": { "type": "array", "items": { "type": "string", "enum": [ "retrieval_request.status_changed", "retrieval_request.action_required", "retrieval_request.documents_available" ] }, "minItems": 1, "description": "Event types to subscribe to" }, "description": { "type": "string", "nullable": true, "description": "Optional webhook description", "maxLength": 500 }, "is_enabled": { "type": "boolean", "description": "Enable or disable webhook" } } }, "WebhookTestResult": { "type": "object", "required": [ "success", "status_code", "duration_ms", "error", "event_id", "sent_at" ], "properties": { "success": { "type": "boolean", "description": "True if your endpoint returned a 2xx response within 5 seconds", "example": false }, "status_code": { "type": "integer", "nullable": true, "description": "HTTP status returned by your endpoint, or null if no response was received", "example": 502 }, "duration_ms": { "type": "integer", "description": "Elapsed test duration, in milliseconds.", "example": 81 }, "error": { "type": "string", "nullable": true, "description": "Failure reason, or null on success. Your endpoint response body is not returned.", "example": "HTTP 502" }, "event_id": { "type": "string", "description": "ID of the `webhook.test` event that was sent", "example": "evt_test_6f1c2a9e-4b7d-4c1e-9a53-0d2f8e7b1c44" }, "sent_at": { "type": "string", "format": "date-time", "example": "2026-10-07T17:30:00.000Z" } } }, "PaginatedCases": { "type": "object", "required": [ "results", "next", "previous" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Case" }, "description": "Array of case objects" }, "next": { "type": "string", "nullable": true, "format": "uri", "description": "URL to next page (null if no more pages)", "example": "https://enterprise.tavrn.ai/v2/cases?limit=20&cursor=next_cursor" }, "previous": { "type": "string", "nullable": true, "format": "uri", "description": "URL to previous page (null if first page)", "example": "https://enterprise.tavrn.ai/v2/cases?limit=20&cursor=prev_cursor" } } }, "PaginatedDocuments": { "type": "object", "required": [ "results", "next", "previous" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } }, "next": { "type": "string", "nullable": true, "format": "uri" }, "previous": { "type": "string", "nullable": true, "format": "uri" } } }, "WebhookList": { "type": "object", "required": [ "webhooks" ], "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" }, "description": "Array of webhook objects" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code", "example": "validation_error" }, "message": { "type": "string", "description": "Human-readable error message", "example": "The patient.date_of_birth field is required" } } } } }, "DuplicateRetrievalRequestError": { "type": "object", "required": [ "error", "duplicates" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "duplicate_request_detected" ] }, "message": { "type": "string" } } }, "duplicates": { "type": "array", "description": "Blocking matches to review before choosing whether to retry with allow_duplicate: true.", "items": { "type": "object", "required": [ "id", "order_number", "classification", "overlapping_record_types", "cross_case" ], "properties": { "id": { "type": "string", "description": "Existing retrieval request ID." }, "order_number": { "type": "string" }, "classification": { "type": "string", "enum": [ "EXACT", "PARTIAL_RECORD_TYPES" ] }, "overlapping_record_types": { "type": "array", "items": { "type": "string" } }, "cross_case": { "type": "boolean", "description": "Whether the match belongs to another case in the same organization." } } } } } }, "DeleteResponse": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "description": "Whether deletion was successful", "example": true } } }, "Patient": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Patient full legal name", "example": "Jane Doe" }, "date_of_birth": { "type": "string", "format": "date", "nullable": true, "description": "YYYY-MM-DD. Strongly recommended \u2014 most facilities require it to match records.", "example": "1989-04-12" }, "address": { "type": "string", "nullable": true, "description": "Patient mailing address. Many facilities verify against this.", "example": "123 Main St, Austin, TX 78701" }, "phone": { "type": "string", "nullable": true, "description": "Patient phone number. Some facilities use this to verify identity or follow up on the request.", "example": "+1-512-555-0101" }, "email": { "type": "string", "format": "email", "nullable": true, "description": "Patient email address. Used by some facilities for identity verification or to send the patient a portal invite.", "example": "jane@example.com" }, "gender": { "type": "string", "nullable": true, "description": "Patient gender. Required by some facilities for identity verification.", "example": "F" }, "ssn": { "type": "string", "nullable": true, "description": "Patient Social Security Number. Many facilities require the last 4 digits for identity verification; supply when known." } }, "description": "Patient details. Supply as much as you know \u2014 many facilities verify identity against DOB, SSN last-4, or address before releasing records." }, "PatientRead": { "type": "object", "required": [ "name", "date_of_birth", "address", "phone", "email", "gender", "ssn" ], "properties": { "name": { "type": "string", "nullable": true, "description": "Patient name, or null when unavailable." }, "date_of_birth": { "type": "string", "format": "date", "nullable": true, "description": "Date of birth, or null when unknown." }, "address": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "gender": { "type": "string", "nullable": true }, "ssn": { "type": "string", "nullable": true, "description": "Always null on public reads; submitted SSNs are not echoed back." } }, "description": "Patient fields returned by retrieval GET and list responses." }, "FacilityRequirement": { "type": "object", "required": [ "slug", "label", "description", "category", "record_types" ], "properties": { "slug": { "type": "string", "description": "Requirement identifier." }, "label": { "type": "string", "description": "Requirement name." }, "description": { "type": "string", "nullable": true, "description": "Additional instructions, when available." }, "category": { "type": "string", "enum": [ "input", "document", "instruction" ] }, "record_types": { "type": "array", "items": { "type": "string" }, "description": "Applicable record categories, such as medical_records, billings, or radiology. Empty means all record types." }, "template_download_url": { "type": "string", "format": "uri", "description": "For document requirements, a download link to a blank template when available. Valid for 1 hour; repeat the facility search for a fresh link. Omitted when unavailable.", "example": "https://example.com/authorization-template.pdf" } } }, "FacilitySearchResult": { "type": "object", "required": [ "id", "name", "requirements" ], "properties": { "id": { "type": "string", "description": "Facility ID to pass as facility_id when creating a retrieval.", "example": "facility_example" }, "name": { "type": "string", "example": "Example General Hospital" }, "requirements": { "type": "array", "items": { "$ref": "#/components/schemas/FacilityRequirement" }, "description": "Requirements for requesting records. Empty when none are listed." } } }, "FacilitySearchResponse": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/FacilitySearchResult" } } }, "description": "Matching facilities. No pagination or total count." }, "Facility": { "type": "object", "required": [ "name", "address_line1", "city", "state", "zip_code" ], "properties": { "name": { "type": "string", "description": "Facility / provider organization name", "example": "Example General Hospital" }, "address_line1": { "type": "string", "description": "Street address", "example": "100 Example Ave" }, "address_line2": { "type": "string", "nullable": true, "description": "Suite, floor, etc.", "example": null }, "city": { "type": "string", "example": "Springfield" }, "state": { "type": "string", "description": "US state code (2 letters)", "example": "PA" }, "zip_code": { "type": "string", "example": "00000" }, "phone": { "type": "string", "nullable": true, "description": "Optional phone contact supplied by your organization. On reads, omitted unless a customer-supplied contact is available for this request.", "example": "+1-555-010-2000" }, "fax": { "type": "string", "nullable": true, "description": "Optional fax contact supplied by your organization. On reads, omitted unless a customer-supplied contact is available for this request.", "example": "+1-555-010-1111" } }, "description": "Facility name and address when creating a request manually. Provide this object or a top-level facility_id. Optional phone and fax contacts may be absent on read." }, "FacilityRead": { "type": "object", "required": [ "name", "address_line1", "address_line2", "city", "state", "zip_code" ], "properties": { "name": { "type": "string", "nullable": true, "description": "Facility or provider name, or null when unavailable." }, "address_line1": { "type": "string", "nullable": true }, "address_line2": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "zip_code": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true, "description": "Returned only when a customer-supplied phone contact is available for this request." }, "fax": { "type": "string", "nullable": true, "description": "Returned only when a customer-supplied fax contact is available for this request." } }, "description": "Facility fields returned by retrieval GET and list responses. Name and address fields may be null, and phone or fax may be omitted." }, "RequestorUploadReference": { "type": "object", "properties": { "upload_id": { "type": "string", "format": "uuid", "description": "Upload ID from POST /v2/requestors/sign-upload after uploading the PDF." } }, "required": [ "upload_id" ], "additionalProperties": false, "nullable": true }, "RequestorAffidavitsInput": { "type": "object", "properties": { "declared_families": { "type": "array", "maxItems": 3, "uniqueItems": true, "items": { "type": "string", "enum": [ "records", "billing", "radiology" ] }, "description": "Replace declared families; [] records an explicit answer of none, including on a new profile. If omitted without exact documents, preserves the previous answer or leaves it unanswered. Supplied exact-document families are added to the existing declaration when this field is omitted. If supplied with documents, every uploaded family must be included." }, "documents": { "type": "array", "maxItems": 3, "items": { "type": "object", "properties": { "family": { "type": "string", "enum": [ "records", "billing", "radiology" ] }, "upload_id": { "type": "string", "format": "uuid" } }, "required": [ "family", "upload_id" ], "additionalProperties": false }, "description": "Replace all exact-family documents, with at most one per family. An empty array removes them all; omission preserves them. Supplied families are added to the declaration unless declared_families is explicitly provided. Updating exact-family documents leaves generic unchanged." }, "generic": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/RequestorUploadReference" } ] } }, "minProperties": 1, "additionalProperties": false, "description": "Generic fallback and exact-family documents are independent. Set generic to null to remove it. Referenced PDFs must be readable, unencrypted, and at most 25 MiB." }, "RequestorCorrespondenceNotice": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 500 }, "body": { "type": "string", "maxLength": 10000 }, "suppress_prepayment_sentence": { "type": "boolean", "nullable": true }, "suppress_provider_cost_threshold_paragraph": { "type": "boolean", "nullable": true } }, "required": [ "title", "body" ], "additionalProperties": false, "nullable": true }, "RequestorBillingInstructions": { "type": "object", "properties": { "special_instruction": { "type": "string", "nullable": true, "maxLength": 10000 }, "cover_letter_ask": { "type": "string", "nullable": true, "maxLength": 10000 }, "auth_scope_stamp_label": { "type": "string", "nullable": true, "maxLength": 500 } }, "additionalProperties": false, "nullable": true }, "RequestorCorrespondence": { "type": "object", "properties": { "custom_letter_body": { "type": "string", "nullable": true, "maxLength": 10000 }, "custom_letter_body_requires_rfc": { "type": "boolean", "nullable": true }, "notice": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/RequestorCorrespondenceNotice" } ] }, "billing_request": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/RequestorBillingInstructions" } ] } }, "additionalProperties": false, "nullable": true, "description": "Omitted settings stay unchanged on update. Null clears nullable settings. A supplied notice replaces the previous notice; supplied billing_request fields merge with existing fields." }, "RequestorCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Nonblank display name used for this profile." }, "provider_invoice_limit": { "type": "number", "minimum": 0, "nullable": true, "description": "Provider invoice approval limit in USD. Null uses $100; 0 prevents automatic payment of positive provider costs." }, "letter_of_rep": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/RequestorUploadReference" } ] }, "rfc_form": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/RequestorUploadReference" } ] }, "affidavits": { "$ref": "#/components/schemas/RequestorAffidavitsInput" }, "correspondence": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/RequestorCorrespondence" } ] } }, "required": [ "name" ], "additionalProperties": false, "description": "Create an independent profile from the supplied configuration. Omitted document and correspondence fields start empty. It does not copy or replace the organization default." }, "RequestorUpdate": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 500, "description": "Name override. Null restores the organization-name fallback; omission preserves the name." }, "provider_invoice_limit": { "type": "number", "minimum": 0, "nullable": true, "description": "Provider invoice approval limit in USD. Null uses $100; 0 prevents automatic payment of positive provider costs." }, "letter_of_rep": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/RequestorUploadReference" } ] }, "rfc_form": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/RequestorUploadReference" } ] }, "affidavits": { "$ref": "#/components/schemas/RequestorAffidavitsInput" }, "correspondence": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/RequestorCorrespondence" } ] } }, "minProperties": 1, "additionalProperties": false, "description": "Update supplied fields only. Null clears nullable document slots/settings; arrays replace their corresponding collection. Changes affect existing linked retrievals." }, "RequestorFile": { "type": "object", "required": [ "file_name", "page_count", "uploaded_at" ], "properties": { "file_name": { "type": "string", "nullable": true }, "page_count": { "type": "integer", "nullable": true }, "uploaded_at": { "type": "string", "nullable": true, "format": "date-time" } }, "nullable": true, "description": "Document metadata returned with a Requestor." }, "Requestor": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "example": "111111111111111111111111" }, "name": { "type": "string", "nullable": true, "description": "Name override, or null to use the organization name." }, "is_default": { "type": "boolean", "description": "Whether this profile is selected when creation omits both Requestor fields." }, "provider_invoice_limit": { "type": "number", "minimum": 0, "nullable": true, "description": "Provider invoice approval limit in USD. Null uses $100; 0 prevents automatic payment of positive provider costs." }, "effective_provider_invoice_limit": { "type": "number", "minimum": 0, "description": "Applied approval limit in USD after resolving null to $100." }, "letter_of_rep": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/RequestorFile" } ] }, "rfc_form": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/RequestorFile" } ] }, "affidavits": { "type": "object", "required": [ "declared_families", "documents", "generic", "config_revision" ], "properties": { "declared_families": { "type": "array", "items": { "type": "string", "enum": [ "records", "billing", "radiology" ] } }, "documents": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/RequestorFile" }, { "type": "object", "properties": { "family": { "type": "string", "enum": [ "records", "billing", "radiology" ] }, "source": { "type": "string", "enum": [ "FIRM_UPLOAD", "TAVRN_DEFAULT" ] } }, "required": [ "family", "source" ] } ] } }, "generic": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/RequestorFile" } ] }, "config_revision": { "type": "integer", "nullable": true } } }, "correspondence": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/RequestorCorrespondence" } ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "is_default", "provider_invoice_limit", "effective_provider_invoice_limit", "letter_of_rep", "rfc_form", "affidavits", "correspondence", "created_at", "updated_at" ] }, "PaginatedRequestors": { "type": "object", "required": [ "results", "next", "previous" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Requestor" } }, "next": { "type": "string", "format": "uri", "nullable": true, "example": "https://enterprise.tavrn.ai/v2/requestors?limit=20&cursor=next_cursor" }, "previous": { "type": "string", "format": "uri", "nullable": true, "example": null } } }, "RetrievalRequestCreate": { "type": "object", "required": [ "patient", "requested_records", "auth_form" ], "properties": { "patient": { "$ref": "#/components/schemas/Patient" }, "facility": { "$ref": "#/components/schemas/Facility" }, "facility_id": { "type": "string", "minLength": 1, "description": "Facility ID from GET /v2/facilities. Provide exactly one of facility_id or facility.", "example": "facility_example" }, "service_start_date": { "type": "string", "format": "date", "nullable": true, "description": "Default start of the service date range (YYYY-MM-DD). Inherited by any `requested_records[]` line that omits its own `service_start_date`.", "example": "2024-03-15" }, "service_end_date": { "type": "string", "format": "date", "nullable": true, "description": "Default end of the service date range (YYYY-MM-DD). Inherited by any `requested_records[]` line that omits its own. Set to `null` for ongoing care.", "example": "2024-09-30" }, "notes": { "type": "string", "nullable": true, "description": "Free-text instructions for the team handling this request", "example": "Please include any radiology read reports" }, "submitter_email": { "type": "string", "format": "email", "nullable": true, "description": "Email of a 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. If omitted, the request is attributed to the creator of the API key.", "example": "jane.smith@example.com" }, "auth_form": { "allOf": [ { "$ref": "#/components/schemas/AuthFormUpload" } ], "description": "The signed HIPAA authorization PDF. Required." }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/UploadedFile" }, "default": [], "description": "Optional supporting documents for the request \u2014 e.g., cover letters, patient ID copies, prior-auth attachments. Each entry references an uploaded file by upload_id." }, "requested_records": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/RequestedRecord" }, "description": "One or more record lines to request. Each line carries its own type, dates, requirements, and (for billing) deliverable format." }, "requestor_id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "example": "111111111111111111111111", "description": "Existing profile in your organization. Mutually exclusive with requestor. Omit both to keep the organization default." }, "requestor": { "allOf": [ { "$ref": "#/components/schemas/RequestorCreate" } ], "description": "Create a Requestor profile with this retrieval. Requires requestors:write and cannot be combined with requestor_id." }, "allow_duplicate": { "type": "boolean", "nullable": true, "description": "When duplicate detection is enabled, retry with true after reviewing a 409 duplicate_request_detected response to create despite the blocking matches. Omission or null does not override the check." } }, "not": { "required": [ "requestor_id", "requestor" ] }, "oneOf": [ { "required": [ "facility" ] }, { "required": [ "facility_id" ] } ] }, "StandaloneRetrievalRequestCreate": { "allOf": [ { "$ref": "#/components/schemas/RetrievalRequestCreate" }, { "type": "object", "properties": { "case_id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "example": "111111111111111111111111", "description": "Existing case in your organization; mutually exclusive with case." }, "case": { "allOf": [ { "$ref": "#/components/schemas/CaseCreate" } ], "description": "Create a case with this retrieval. Requires cases:write and cannot be combined with case_id." } }, "oneOf": [ { "required": [ "case_id" ], "not": { "required": [ "case" ] } }, { "required": [ "case" ], "not": { "required": [ "case_id" ] } } ] } ] }, "RetrievalRequest": { "type": "object", "required": [ "id", "order_number", "case_id", "status", "stage", "stage_label", "patient", "facility", "requested_records", "documents_summary", "created_at", "updated_at", "requestor_id", "public_updated_at" ], "properties": { "id": { "type": "string", "description": "Unique retrieval request identifier", "example": "rr_abc123" }, "order_number": { "type": "string", "nullable": true, "description": "Human-readable order number, or null when unavailable.", "example": "T-ABC-12345" }, "case_id": { "type": "string", "description": "Associated case ID", "example": "case_abc123", "nullable": true }, "platform_url": { "type": "string", "nullable": true, "description": "Deep link to this retrieval request on the Tavrn platform dashboard; null when the request has no linked case", "example": "https://platform.tavrn.ai/cases/case_abc123?section=workflows%2Fretrieval-manager&view=detail&orderId=rr_abc123" }, "status": { "type": "string", "enum": [ "received", "processing", "action_required", "completed", "cancelled" ], "description": "Coarse public retrieval status. `completed` and `cancelled` are terminal. A non-terminal request with an unanswered action request (a timeline `action_request` with status `awaiting_response`) is always `action_required`.", "example": "processing" }, "action_required_reason": { "type": "string", "enum": [ "payment_needed", "contact_missing", "request_issue", "other" ], "nullable": true, "description": "Sub-reason when status is action_required; null otherwise", "example": null }, "stage": { "$ref": "#/components/schemas/RetrievalStage" }, "stage_label": { "type": "string", "description": "Human-readable label for `stage`, as shown on the Tavrn platform dashboard", "example": "Request Acknowledged" }, "stage_description": { "type": "string", "nullable": true, "description": "Plain-language sentence for the current stage, as shown on the Tavrn platform dashboard. Null when there is nothing to show yet.", "example": "Your request is in progress with the provider. We follow up with them regularly and will post updates here." }, "timeline": { "type": "array", "items": { "$ref": "#/components/schemas/RetrievalTimelineEntry" }, "description": "Ordered lifecycle of the request as rendered on the Tavrn platform dashboard. The standard steps (submitted, locating_contact, contact_found, request_sent, confirming_receipt, acknowledged, completed) always appear, each with a state of completed, current, pending or skipped. Conditional stages (invoice_received, action_required, cancelled) appear only when they occurred, so a stage may be absent, and action_required repeats once per action request. Returned by GET and by list with include=details; omitted from summary list results." }, "pending_action_request": { "$ref": "#/components/schemas/PendingActionRequest" }, "patient": { "$ref": "#/components/schemas/PatientRead" }, "facility": { "$ref": "#/components/schemas/FacilityRead" }, "service_start_date": { "type": "string", "format": "date", "nullable": true, "example": "2024-03-15" }, "service_end_date": { "type": "string", "format": "date", "nullable": true, "example": "2024-09-30" }, "notes": { "type": "string", "nullable": true, "example": null }, "documents_summary": { "type": "object", "description": "Counts records and provider invoices; excludes cost summaries.", "required": [ "records_count", "invoices_count" ], "properties": { "records_count": { "type": "integer", "description": "Number of record documents available", "example": 2 }, "invoices_count": { "type": "integer", "description": "Number of provider invoices in the response", "example": 1 } } }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/RetrievalRequestDocument" }, "description": "Available retrieval documents, including cost_summary for completed requests with finalized billing. Returned by GET and list results with include=details." }, "created_at": { "type": "string", "format": "date-time", "example": "2025-02-01T12:50:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2025-02-03T09:14:21Z" }, "public_updated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp for public request changes, including status, action requests, and documents. Costs may change without advancing it. Use the final list checkpoint, not this field, for incremental polling. May be null.", "example": "2026-10-08T12:00:00.000Z" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Completion timestamp (null until terminal)", "example": null }, "requested_records": { "type": "array", "items": { "$ref": "#/components/schemas/RequestedRecordRead" }, "description": "The record lines that were requested from the facility" }, "requestor_id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "example": "111111111111111111111111", "nullable": true, "description": "Selected Requestor profile ID. A null read value uses the default profile. Omitting Requestor fields on creation also uses the default." } } }, "RetrievalRequestDetails": { "allOf": [ { "$ref": "#/components/schemas/RetrievalRequest" }, { "type": "object", "required": [ "costs" ], "properties": { "costs": { "type": "object", "description": "Current request costs, returned by the get endpoint only. Amounts are in USD, not cents. Costs can change after completion without advancing public_updated_at or producing a webhook; fetch the request again when you need current costs. A documents_available event is sent when a provider invoice becomes downloadable.", "required": [ "tavrn_credits_consumed", "tavrn_fee", "provider_fees", "total_cost" ], "properties": { "tavrn_credits_consumed": { "type": "number", "nullable": true, "description": "Tavrn credits consumed by this request, net of refunds; null when unavailable.", "example": 1 }, "tavrn_fee": { "type": "number", "nullable": true, "description": "Tavrn fee for this request in USD; null when unavailable.", "example": 35 }, "provider_fees": { "type": "number", "description": "Sum of returned provider invoice amounts in USD; zero when none are available.", "example": 85 }, "total_cost": { "type": "number", "nullable": true, "description": "Sum of tavrn_fee and provider_fees in USD; null when tavrn_fee is unavailable.", "example": 120 } } } } } ] }, "RetrievalStage": { "type": "string", "enum": [ "submitted", "locating_contact", "contact_found", "request_sent", "confirming_receipt", "acknowledged", "invoice_received", "action_required", "completed", "cancelled" ], "description": "Lifecycle stage shown on the Tavrn platform dashboard.", "example": "acknowledged" }, "RetrievalTimelineEntry": { "type": "object", "required": [ "stage", "stage_label", "state", "occurred_at", "description", "checkpoints", "action_request" ], "properties": { "stage": { "$ref": "#/components/schemas/RetrievalStage" }, "stage_label": { "type": "string", "description": "Label for this step. For an answered action request this is `Action Response Received`.", "example": "Correspondence Sent" }, "state": { "type": "string", "enum": [ "completed", "current", "pending", "skipped" ], "description": "`completed` \u2014 step happened; `current` \u2014 the request is here now; `pending` \u2014 standard step not reached yet; `skipped` \u2014 standard step that was not needed for this request.", "example": "completed" }, "occurred_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the request entered this step; null for pending and skipped steps", "example": "2025-02-02T10:30:00Z" }, "description": { "type": "string", "nullable": true, "description": "Plain-language sentence for this step, as shown on the Tavrn platform dashboard", "example": "We've sent out your request via fax and will be following up with the provider to check in on progress." }, "checkpoints": { "type": "array", "items": { "type": "object", "required": [ "text", "occurred_at" ], "properties": { "text": { "type": "string", "example": "Call completed at 2:14 PM to the facility." }, "occurred_at": { "type": "string", "format": "date-time", "example": "2025-02-01T19:14:00Z" } } }, "description": "Individual attempts within this step, e.g. calls made while locating a contact or confirming receipt" }, "action_request": { "type": "object", "nullable": true, "description": "Present on `action_required` steps: what Tavrn asked your firm for and how it was answered", "required": [ "id", "status", "description", "response_text", "responded_at", "has_attachment" ], "properties": { "id": { "type": "string", "example": "car_abc123" }, "status": { "type": "string", "enum": [ "awaiting_response", "answered", "resolved" ], "description": "`awaiting_response` \u2014 your firm still needs to respond; `answered` \u2014 your firm responded; `resolved` \u2014 closed by Tavrn without a response", "example": "answered" }, "description": { "type": "string", "description": "What was asked of your firm", "example": "Please upload a signed HIPAA authorization dated within the last 12 months." }, "response_text": { "type": "string", "nullable": true, "example": "Uploaded the updated authorization." }, "responded_at": { "type": "string", "format": "date-time", "nullable": true, "example": "2025-02-03T16:05:00Z" }, "has_attachment": { "type": "boolean", "description": "True when a document was attached to the request or the response", "example": true } } } } }, "RetrievalRequestCreateResponse": { "type": "object", "required": [ "id", "order_number", "case_id", "status", "created_at", "updated_at", "requestor_id" ], "properties": { "id": { "type": "string", "example": "rr_abc123" }, "order_number": { "type": "string", "example": "T-ABC-12345" }, "case_id": { "type": "string", "example": "case_abc123" }, "status": { "type": "string", "enum": [ "received", "processing", "action_required", "completed", "cancelled" ], "example": "received" }, "created_at": { "type": "string", "format": "date-time", "example": "2025-02-01T12:50:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2025-02-01T12:50:00Z" }, "requestor_id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "example": "111111111111111111111111", "nullable": true, "description": "Selected Requestor profile ID." } } }, "RetrievalRequestDocument": { "type": "object", "required": [ "id", "retrieval_request_id", "category", "record_types", "file_name", "file_size", "file_type", "page_count", "created_at" ], "properties": { "id": { "type": "string", "description": "Opaque document identifier. For an invoice, it matches the ID in webhook invoice_ids. The request cost PDF uses cost_summary.", "example": "rrdoc_001" }, "retrieval_request_id": { "type": "string", "example": "rr_abc123" }, "category": { "type": "string", "enum": [ "records", "invoice", "cost_summary" ], "description": "`records` for facility records, `invoice` for provider invoices, `cost_summary` for completed request costs once billing is finalized.", "example": "records" }, "record_types": { "type": "array", "items": { "type": "string" }, "description": "Content categories, commonly medical_records, billings, radiology, abstract_records, or other. Additional values may appear. Empty for invoices and cost summaries.", "example": [ "medical_records" ] }, "metadata": { "type": "object", "description": "Present for invoice documents only; omitted for records and cost summaries.", "required": [ "provider_fee_amount" ], "properties": { "provider_fee_amount": { "type": "number", "minimum": 0, "description": "This provider invoice's amount in USD, not cents, contributing to costs.provider_fees. Zero is a valid amount.", "example": 85 } } }, "file_name": { "type": "string", "nullable": true, "description": "File name, or null when unavailable.", "example": "example_general_hospital_records.pdf" }, "file_size": { "type": "integer", "nullable": true, "example": 2456789 }, "file_type": { "type": "string", "nullable": true, "description": "MIME type, or null when unavailable.", "example": "application/pdf" }, "page_count": { "type": "integer", "nullable": true, "example": 134 }, "created_at": { "type": "string", "format": "date-time", "nullable": true, "example": "2025-02-05T15:22:10Z" } }, "description": "An invoice can appear in this list and in costs before it is downloadable. Its download endpoint returns 404 until the file is available." }, "CancelRetrievalRequestResponse": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "string", "example": "rr_abc123" }, "status": { "type": "string", "enum": [ "cancelled" ], "example": "cancelled" } } }, "PaginatedRetrievalRequests": { "type": "object", "required": [ "results", "next", "previous" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/RetrievalRequest" } }, "next": { "type": "string", "format": "uri", "nullable": true, "example": "https://enterprise.tavrn.ai/v2/retrieval-requests?limit=20&cursor=next_cursor" }, "previous": { "type": "string", "format": "uri", "nullable": true, "example": null }, "scan_until": { "type": "string", "format": "date-time", "description": "Upper time bound for this polling round. Present only with public_updated_since; do not use it as the next checkpoint.", "example": "2026-10-08T12:00:00.000Z" }, "next_public_updated_since": { "type": "string", "format": "date-time", "description": "Checkpoint returned only on the final incremental page, including an empty final page. Save after processing every page and use it as the next public_updated_since. Results can repeat across rounds.", "example": "2026-10-08T11:58:00.000Z" } } }, "RetrievalRequestDocumentsResponse": { "type": "object", "description": "Complete current document list in one response. This endpoint does not paginate or filter by category; next and previous are always null.", "required": [ "results", "next", "previous" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/RetrievalRequestDocument" } }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "Always null for this endpoint.", "example": null }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "Always null for this endpoint.", "example": null } } }, "UploadedFile": { "type": "object", "required": [ "upload_id", "file_name" ], "properties": { "upload_id": { "type": "string", "description": "Upload ID from POST /v2/retrieval-requests/sign-upload or the matching case sign-upload endpoint, after uploading the file.", "example": "11111111-1111-4111-8111-111111111111" }, "file_name": { "type": "string", "description": "Original file name", "example": "jane_doe_hipaa.pdf" } } }, "AuthFormUpload": { "allOf": [ { "$ref": "#/components/schemas/UploadedFile" }, { "type": "object", "properties": { "signer_name": { "type": "string", "nullable": true, "description": "Full name of the person who signed the authorization, if not the patient (e.g., parent of a minor, legal guardian, power of attorney). Omit or null when the patient signed.", "example": "Mary Doe" }, "signer_relationship": { "type": "string", "nullable": true, "description": "Relationship of the signer to the patient (free text \u2014 e.g., 'Parent', 'Legal Guardian', 'POA'). Only meaningful when signer_name is set.", "example": "Mother" } } } ], "description": "Reference to the signed HIPAA authorization PDF, plus optional metadata about who signed it when the signer is not the patient." }, "RequestedRecord": { "type": "object", "required": [ "type" ], "description": "A single record line on a retrieval request. Each line targets one record type, with its own date range, requirements, and (for billing types) a deliverable format. A request may include multiple lines of the same `type` with different dates or formats.", "properties": { "type": { "type": "string", "enum": [ "medical_records", "medical_records_er", "medical_records_mental_health", "abstract_medical_records", "radiology_reports", "rfc", "custom_medical", "billings", "billing_physician", "billing_institutional", "billing_er", "billing_radiology", "billing_anesthesiology", "billing_ambulance", "custom_billing", "imaging", "custom_imaging" ], "description": "The record type. Grouped by category \u2014 medical, billing, imaging \u2014 and including `custom_*` slots for record types not in the catalog. See the schemas guide for descriptions of each value. Some values (`rfc`, `abstract_medical_records`) are available only when enabled for your organization.", "example": "medical_records" }, "custom_label": { "type": "string", "nullable": true, "description": "Free-text label for a `custom_*` type. Required when `type` starts with `custom_`. Ignored for all other types.", "example": null }, "deliverable_format": { "type": "string", "enum": [ "itemized", "account_balance", "insurance_claim_form" ], "nullable": true, "description": "Format requested from the facility for billing-category lines. Required when `type` is a billing definition (`billings`, `billing_*`, or `custom_billing`); omit for non-billing types. Submit multiple lines of the same billing `type` to request more than one format (e.g. itemized + account balance).", "example": null }, "service_start_date": { "type": "string", "format": "date", "nullable": true, "description": "Start of the service date range for this line (YYYY-MM-DD). Inherits the request-level `service_start_date` if omitted or null.", "example": "2024-03-15" }, "service_end_date": { "type": "string", "format": "date", "nullable": true, "description": "End of the service date range for this line (YYYY-MM-DD). Inherits the request-level `service_end_date` if omitted. Set to `null` to request records through the present (ongoing care).", "example": "2024-09-30" }, "requirements": { "type": "array", "items": { "type": "string", "enum": [ "certification", "affidavit" ] }, "default": [], "description": "Per-line documentation requirements. `certification` asks the facility to certify the records; `affidavit` asks for an affidavit attesting to authenticity. A single request may use only one of these kinds 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 `certification` and `affidavit` (on the same or different lines) is rejected with `400 validation_error` (`requested_records cannot include both \"affidavit\" and \"certification\" requirements; choose one attestation per request`). Each value is available only when enabled for your organization \u2014 contact Tavrn support to enable." } } }, "RequestedRecordRead": { "type": "object", "required": [ "type", "custom_label", "deliverable_format", "service_start_date", "service_end_date", "requirements" ], "description": "Record line returned by retrieval GET and list responses. Read values can differ from values accepted on new requests.", "properties": { "type": { "type": "string", "description": "Record type returned for this request.", "example": "medical_records" }, "custom_label": { "type": "string", "nullable": true }, "deliverable_format": { "type": "string", "nullable": true, "description": "Format returned for this record line; it may differ from values accepted on creation.", "example": "itemized" }, "service_start_date": { "type": "string", "format": "date", "nullable": true }, "service_end_date": { "type": "string", "format": "date", "nullable": true }, "requirements": { "type": "array", "items": { "type": "string" } } } }, "ActionResponseCreate": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 10000, "description": "Your answer to the action request. Leading and trailing whitespace is trimmed; must not be empty.", "example": "Approved. Please pay the $85.00 invoice." }, "requester_email": { "type": "string", "format": "email", "description": "Email of the person at your firm who answered. Recorded as the responder; defaults to the API key.", "example": "paralegal@yourfirm.com" }, "attachment": { "$ref": "#/components/schemas/ActionResponseAttachment" } } }, "ActionResponseAttachment": { "type": "object", "required": [ "upload_id" ], "description": "A file to send with the response, uploaded under the retrieval request's case.", "properties": { "upload_id": { "type": "string", "description": "`upload_id` from [Request presigned upload URL](/api-reference/v2/endpoint/cases/sign-upload) for the retrieval request's case. PUT the file to `upload_url` within 15 minutes, then use the `upload_id` within one hour. Each `upload_id` can be used once.", "example": "11111111-1111-4111-8111-111111111111" } } }, "ActionResponse": { "type": "object", "required": [ "id", "retrieval_request_id", "status", "responded_at" ], "properties": { "id": { "type": "string", "description": "ID of the action request that was answered (matches `pending_action_request.id`)", "example": "car_abc123" }, "retrieval_request_id": { "type": "string", "example": "rr_abc123" }, "status": { "type": "string", "enum": [ "responded" ], "example": "responded" }, "responded_at": { "type": "string", "format": "date-time", "example": "2025-02-03T16:05:00Z" } } }, "PendingActionRequest": { "type": "object", "nullable": true, "description": "The open action request your firm needs to answer with [Respond to action request](/api-reference/v2/endpoint/retrieval-requests/respond-to-action-request); `null` when there is none. Returned by the get endpoint and list with include=details.", "required": [ "id", "description", "document" ], "properties": { "id": { "type": "string", "example": "car_abc123" }, "description": { "type": "string", "description": "What Tavrn needs from your firm", "example": "The provider's invoice of $85.00 exceeds your approval limit. Do you approve payment?" }, "document": { "type": "object", "nullable": true, "description": "File Tavrn attached to the action request (for example the provider's invoice or letter); `null` when none", "required": [ "file_name", "file_size", "file_type", "download_url", "expires_in" ], "properties": { "file_name": { "type": "string", "example": "provider_invoice.pdf", "nullable": true }, "file_size": { "type": "integer", "nullable": true, "example": 45123 }, "file_type": { "type": "string", "nullable": true, "example": "application/pdf" }, "download_url": { "type": "string", "description": "Presigned download URL", "example": "https://s3.amazonaws.com/..." }, "expires_in": { "type": "integer", "description": "Seconds until `download_url` expires", "example": 3600 }, "expires_at": { "type": "string", "format": "date-time", "description": "When the download URL expires. Fetch the request again for a fresh URL.", "example": "2026-10-08T13:00:00.000Z" } } } } }, "RetrievalWebhookEvent": { "type": "object", "additionalProperties": false, "required": [ "id", "type", "created_at", "data" ], "description": "IDs-only retrieval event. Fetch the identified request for current status, action text, and document details. Retries preserve the event ID; a later occurrence gets a new ID. Notifications can be duplicated or arrive out of order, so reconcile with incremental polling.", "properties": { "id": { "type": "string", "description": "Opaque event ID for deduplicating deliveries" }, "type": { "type": "string", "enum": [ "retrieval_request.status_changed", "retrieval_request.action_required", "retrieval_request.documents_available" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp assigned to the triggering public change" }, "data": { "type": "object", "additionalProperties": false, "required": [ "retrieval_request_id", "case_id", "public_updated_at" ], "properties": { "retrieval_request_id": { "type": "string", "description": "Request to fetch for current state", "example": "507f1f77bcf86cd799439011" }, "case_id": { "type": "string", "nullable": true, "description": "Associated case ID, or null when the request has no case", "example": "507f1f77bcf86cd799439012" }, "public_updated_at": { "type": "string", "format": "date-time", "description": "Version that triggered this event. Not a full snapshot version or polling checkpoint." }, "action_request_id": { "type": "string", "description": "Present only on `retrieval_request.action_required`; identifies the action request opened or reopened." }, "document_ids": { "type": "array", "description": "Present on `retrieval_request.documents_available`; IDs match public retrieval document IDs. An invoice event includes its invoice ID here.", "items": { "type": "string" } }, "invoice_ids": { "type": "array", "description": "Present on a downloadable provider invoice event; these IDs also appear in `document_ids`.", "items": { "type": "string" } } } } } }, "RetrievalSupportMessageCreate": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 10000, "description": "Support message. Must contain non-whitespace text." }, "requester_name": { "type": "string", "maxLength": 200, "description": "Sender's display name." }, "requester_email": { "type": "string", "format": "email", "description": "Delivery address. Required when API submissions explicitly select email." }, "contact_preference": { "type": "string", "enum": [ "email", "in_app_only", "do_not_contact" ], "description": "email sends receipts and replies by email. in_app_only logs replies without email; automated replies are currently disabled. do_not_contact processes requested work without customer receipts or replies, except for Litify's initial receipt when requester_email is supplied. If omitted, request_response: false selects do_not_contact; otherwise email." }, "request_response": { "type": "boolean", "deprecated": true, "description": "Used when contact_preference is omitted: true (default) means email; false means do_not_contact." }, "attachment": { "type": "object", "required": [ "upload_id" ], "properties": { "upload_id": { "type": "string", "description": "ID returned by the case sign-upload endpoint for this request's case.", "minLength": 1 } } } } }, "RetrievalSupportMessage": { "type": "object", "required": [ "id", "retrieval_request_id", "status" ], "properties": { "id": { "type": "string", "description": "Opaque support conversation ID." }, "retrieval_request_id": { "type": "string" }, "status": { "type": "string", "enum": [ "sent" ], "description": "Submitted; does not confirm task completion or provider delivery." }, "created_at": { "type": "string", "format": "date-time", "description": "Submission timestamp; omitted for a deduplicated resend." }, "deduplicated": { "type": "boolean", "description": "True for an identical submission within 10 minutes." } } } } }, "paths": { "/v2/cases": { "get": { "summary": "List cases", "description": "List all cases with cursor-based pagination", "operationId": "listCases", "tags": [ "Cases" ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of results (default 20, max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor (opaque)", "schema": { "type": "string" } }, { "name": "external_id", "in": "query", "description": "Filter by external ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedCases" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a case", "description": "Create a new legal case", "operationId": "createCase", "tags": [ "Cases" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseCreate" } } } }, "responses": { "201": { "description": "Case created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Case" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/cases/{case_id}": { "get": { "summary": "Get case by ID", "description": "Retrieve a specific case by its ID", "operationId": "getCase", "tags": [ "Cases" ], "parameters": [ { "name": "case_id", "in": "path", "required": true, "description": "Case ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Case" } } } }, "404": { "description": "Case not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update case", "description": "Update case fields (partial update)", "operationId": "updateCase", "tags": [ "Cases" ], "parameters": [ { "name": "case_id", "in": "path", "required": true, "description": "Case ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseUpdate" } } } }, "responses": { "200": { "description": "Case updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Case" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Case not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/cases/{case_id}/documents": { "post": { "summary": "Create document record", "description": "Create a document record after uploading the file via the presigned URL", "operationId": "createDocument", "tags": [ "Documents" ], "parameters": [ { "name": "case_id", "in": "path", "required": true, "description": "Case ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentCreate" } } } }, "responses": { "201": { "description": "Document created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Upload ID not found or case not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/documents": { "get": { "summary": "List all documents", "description": "List all documents across cases", "operationId": "listDocuments", "tags": [ "Documents" ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of results", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor", "schema": { "type": "string" } }, { "name": "case_id", "in": "query", "description": "Filter by case ID", "schema": { "type": "string" } }, { "name": "archived", "in": "query", "description": "Filter by archived status", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedDocuments" } } } } } } }, "/v2/documents/{document_id}": { "get": { "summary": "Get document by ID", "description": "Retrieve a specific document by its ID", "operationId": "getDocument", "tags": [ "Documents" ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "description": "Document ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update document", "description": "Update document metadata or archive status", "operationId": "updateDocument", "tags": [ "Documents" ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "description": "Document ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentUpdate" } } } }, "responses": { "200": { "description": "Document updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/documents/{document_id}/download": { "get": { "summary": "Download document", "description": "Get a presigned download URL for a document (valid for 1 hour)", "operationId": "downloadDocument", "tags": [ "Documents" ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "description": "Document ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Presigned download URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/webhooks": { "get": { "summary": "List webhooks", "description": "List all webhooks for the organization. Requires `webhooks:read`; secrets are not returned.", "operationId": "listWebhooks", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookList" } } } } } }, "post": { "summary": "Create webhook", "description": "Register a new webhook endpoint. Requires `webhooks:write`; subscribing to retrieval events also requires `retrievals:read`. The secret is returned only in this response.", "operationId": "createWebhook", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreate" } } } }, "responses": { "201": { "description": "Webhook created successfully (secret is ONLY returned here!)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreateResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks a scope required by the requested events (for example, retrievals:read for a retrieval request event).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A webhook with this name already exists, or `limit_exceeded`: the organization already has the maximum of 20 webhooks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/webhooks/{id}": { "get": { "summary": "Get webhook by ID", "description": "Retrieve a specific webhook by its ID. Requires `webhooks:read`; the secret is not returned.", "operationId": "getWebhook", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "404": { "description": "Webhook not found. Ids that belong to another organization are indistinguishable from unknown ids.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update webhook", "description": "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`.", "operationId": "updateWebhook", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUpdate" } } } }, "responses": { "200": { "description": "Webhook updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks a scope required by the requested events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Webhook not found. Ids that belong to another organization are indistinguishable from unknown ids.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A webhook with this name already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete webhook", "description": "Delete a webhook endpoint. Requires `webhooks:write`.", "operationId": "deleteWebhook", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResponse" } } } }, "404": { "description": "Webhook not found. Ids that belong to another organization are indistinguishable from unknown ids.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/webhooks/{id}/test": { "post": { "summary": "Send test event", "description": "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 fields. One test per webhook is allowed every 10 seconds.", "operationId": "sendTestWebhook", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Test delivery attempted (check `success`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestResult" } } } }, "404": { "description": "Webhook not found. Ids that belong to another organization are indistinguishable from unknown ids.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "A test event was sent to this webhook less than 10 seconds ago", "headers": { "Retry-After": { "description": "Seconds until you can send another test", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "A test event was sent to this webhook less than 10 seconds ago. Try again shortly." } } } } } } } }, "/v2/facilities": { "get": { "summary": "Search facilities", "description": "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.", "operationId": "searchFacilities", "tags": [ "Retrieval Requests" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search text, trimmed before validation. Must contain at least 3 alphanumeric characters.", "schema": { "type": "string", "minLength": 3, "maxLength": 200 }, "example": "Example Hospital" }, { "name": "state", "in": "query", "description": "Optional uppercase US state code.", "schema": { "type": "string", "pattern": "^[A-Z]{2}$" }, "example": "PA" }, { "name": "limit", "in": "query", "description": "Maximum results to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 10 } } ], "responses": { "200": { "description": "Matching facilities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilitySearchResponse" }, "example": { "results": [ { "id": "facility_example", "name": "Example General Hospital", "requirements": [] } ] } } } }, "400": { "description": "Invalid search parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Requires retrievals:read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait for Retry-After before trying again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "Search temporarily unavailable; try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/cases/{case_id}/retrieval-requests": { "post": { "summary": "Create retrieval request", "description": "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. Use an API key with retrievals:write for creation, plus requestors:write for an inline Requestor. Upload the authorization with POST /v2/retrieval-requests/sign-upload or the case sign-upload endpoint. Use POST /v2/retrieval-requests to create an inline case. Each successful POST with an inline Requestor creates a new profile; retain its ID for reuse.", "operationId": "createRetrievalRequest", "tags": [ "Retrieval Requests" ], "parameters": [ { "name": "case_id", "in": "path", "required": true, "description": "Case ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalRequestCreate" } } } }, "responses": { "201": { "description": "Retrieval request created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalRequestCreateResponse" } } } }, "400": { "description": "Validation error \u2014 for example, `requested_records` mixes `certification` and `affidavit` requirements (only one attestation kind is allowed per request)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Case or Requestor not found in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Blocking similar requests were detected when duplicate detection is enabled. Review duplicates before retrying with allow_duplicate: true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicateRetrievalRequestError" } } } } } } }, "/v2/retrieval-requests": { "get": { "summary": "List retrieval requests", "description": "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 history or deletion feed. Omit mutable status, stage, and case filters for a complete sync. Ordinary listing remains available without public_updated_since.", "operationId": "listRetrievalRequests", "tags": [ "Retrieval Requests" ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of results", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by coarse retrieval status", "schema": { "type": "string", "enum": [ "received", "processing", "action_required", "completed", "cancelled" ] } }, { "name": "stage", "in": "query", "description": "Filter by lifecycle stage. Accepts a single stage or a comma-separated list (e.g. `request_sent,acknowledged`). May be combined with `status`.", "schema": { "type": "string" }, "example": "request_sent,acknowledged" }, { "name": "case_id", "in": "query", "description": "Filter by case ID", "schema": { "type": "string" } }, { "name": "created_after", "in": "query", "description": "Exclusive creation timestamp lower bound (ISO 8601). May be combined with created_before.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "description": "Exclusive creation timestamp upper bound. May be combined with created_after.", "schema": { "type": "string", "format": "date-time" } }, { "name": "public_updated_since", "in": "query", "description": "Inclusive lower bound for retrieval changes included in incremental polling. Start with the epoch for an initial full sync, then use the prior completed round's next_public_updated_since. Do not derive it from your clock or event timestamps.", "schema": { "type": "string", "format": "date-time" } }, { "name": "include", "in": "query", "description": "Include timeline, pending client action, and document metadata in each result. Without it, returns summaries.", "schema": { "type": "string", "enum": [ "details" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedRetrievalRequests" } } } }, "400": { "description": "Invalid query or cursor; restart with the last completed checkpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; retry without advancing the checkpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create retrieval with case and Requestor", "description": "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 default. Inline case and requestor objects can be created together with the retrieval. Upload authorization forms and attachments through POST /v2/retrieval-requests/sign-upload, and Requestor profile documents through POST /v2/requestors/sign-upload, before creating the retrieval. Requires retrievals:write, plus cases:write for an inline case and requestors:write for an inline Requestor. Each successful POST with an inline case or Requestor creates a new one; retain the returned IDs for reuse.", "operationId": "createStandaloneRetrievalRequest", "tags": [ "Retrieval Requests" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandaloneRetrievalRequestCreate" } } } }, "responses": { "201": { "description": "Retrieval request created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalRequestCreateResponse" } } } }, "400": { "description": "Validation error \u2014 for example, `requested_records` mixes `certification` and `affidavit` requirements (only one attestation kind is allowed per request)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Case or Requestor not found in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Blocking similar requests were detected when duplicate detection is enabled. Review duplicates before retrying with allow_duplicate: true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicateRetrievalRequestError" } } } } } } }, "/v2/retrieval-requests/{retrieval_request_id}": { "get": { "summary": "Get retrieval request", "description": "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.", "operationId": "getRetrievalRequest", "tags": [ "Retrieval Requests" ], "parameters": [ { "name": "retrieval_request_id", "in": "path", "required": true, "description": "Retrieval request ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalRequestDetails" } } } }, "404": { "description": "Retrieval request not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable; retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/retrieval-requests/{retrieval_request_id}/cancel": { "post": { "summary": "Cancel retrieval request", "description": "Cancel a retrieval request. Cancellation is final and only allowed while the request is non-terminal.", "operationId": "cancelRetrievalRequest", "tags": [ "Retrieval Requests" ], "parameters": [ { "name": "retrieval_request_id", "in": "path", "required": true, "description": "Retrieval request ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retrieval request cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelRetrievalRequestResponse" } } } }, "400": { "description": "Request is already terminal and cannot be cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Retrieval request not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/retrieval-requests/{retrieval_request_id}/action-response": { "post": { "summary": "Respond to action request", "description": "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 [Request presigned upload URL](/api-reference/v2/endpoint/cases/sign-upload). Some action requests require an attachment: a missing HIPAA authorization must be answered with a signed PDF. A rejected response returns `400` and leaves the action request open so you can retry. See [Responding to action requests](/guides/v2/retrieval-guide#responding-to-action-requests).", "operationId": "respondToActionRequest", "tags": [ "Retrieval Requests" ], "parameters": [ { "name": "retrieval_request_id", "in": "path", "required": true, "description": "Retrieval request ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionResponseCreate" } } } }, "responses": { "200": { "description": "Response recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionResponse" } } } }, "400": { "description": "Validation error: missing or too-long `message`, invalid `requester_email`, an `upload_id` that is unknown, expired, already used, empty, or belongs to a different case, or an attachment the action request does not accept (for example a non-PDF HIPAA authorization). The action request stays open.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the `retrievals:write` scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Retrieval request not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The retrieval request has no open action request (none was raised, or it was already answered or resolved)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/retrieval-requests/{retrieval_request_id}/documents": { "get": { "summary": "List retrieval documents", "description": "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.", "operationId": "listRetrievalDocuments", "tags": [ "Retrieval Requests" ], "parameters": [ { "name": "retrieval_request_id", "in": "path", "required": true, "description": "Retrieval request ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Available retrieval documents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalRequestDocumentsResponse" } } } }, "404": { "description": "Retrieval request not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/retrieval-requests/{retrieval_request_id}/documents/{document_id}/download": { "get": { "summary": "Download retrieval document", "description": "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.", "operationId": "downloadRetrievalDocument", "tags": [ "Retrieval Requests" ], "parameters": [ { "name": "retrieval_request_id", "in": "path", "required": true, "description": "Retrieval request ID", "schema": { "type": "string" } }, { "name": "document_id", "in": "path", "required": true, "description": "Retrieval document ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Presigned download URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/cases/{case_id}/sign-upload": { "post": { "summary": "Request presigned upload URL", "description": "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/retrieval-requests/create-retrieval-request). Supply `file_name` and `file_type`.", "operationId": "signUpload", "tags": [ "Cases" ], "parameters": [ { "name": "case_id", "in": "path", "required": true, "description": "Case ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignUploadRequest" } } } }, "responses": { "200": { "description": "Presigned URL generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignUploadResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Case not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/cases/{case_id}/documents/sign-upload": { "post": { "summary": "Request presigned upload URL (deprecated)", "description": "**Deprecated.** Use [`POST /v2/cases/{case_id}/sign-upload`](/api-reference/v2/endpoint/cases/sign-upload) instead. Request and response shapes are the same.", "operationId": "signUploadDocumentsLegacy", "deprecated": true, "tags": [ "Cases" ], "parameters": [ { "name": "case_id", "in": "path", "required": true, "description": "Case ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignUploadRequest" } } } }, "responses": { "200": { "description": "Presigned URL generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignUploadResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Case not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/requestors": { "get": { "summary": "List Requestors", "operationId": "listRequestors", "tags": [ "Requestors" ], "description": "List your organization's Requestor profiles. is_default identifies the default profile. Requires requestors:read.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 1000 }, "description": "Opaque cursor from next or previous." } ], "responses": { "200": { "description": "Profiles returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedRequestors" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create Requestor", "operationId": "createRequestor", "tags": [ "Requestors" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestorCreate" } } } }, "responses": { "201": { "description": "Profile created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Requestor" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Referenced upload not found or expired in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/requestors/{requestor_id}": { "get": { "summary": "Get Requestor", "operationId": "getRequestor", "tags": [ "Requestors" ], "description": "Read a Requestor profile. Requires requestors:read. An unavailable ID returns 404.", "parameters": [ { "name": "requestor_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "example": "111111111111111111111111" } } ], "responses": { "200": { "description": "Profile returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Requestor" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requestor not found in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update Requestor", "operationId": "updateRequestor", "tags": [ "Requestors" ], "description": "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, or reassign retrievals.", "parameters": [ { "name": "requestor_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "example": "111111111111111111111111" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestorUpdate" } } } }, "responses": { "200": { "description": "Profile updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Requestor" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requestor not found in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict; retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/requestors/sign-upload": { "post": { "summary": "Get Requestor document upload URL", "operationId": "signRequestorUpload", "tags": [ "Requestors" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationSignUploadRequest" } } } }, "responses": { "200": { "description": "Presigned URL generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationSignUploadResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/retrieval-requests/sign-upload": { "post": { "summary": "Get retrieval file upload URL", "operationId": "signRetrievalUpload", "tags": [ "Retrieval Requests" ], "description": "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 one hour.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationSignUploadRequest" } } } }, "responses": { "200": { "description": "Presigned URL generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationSignUploadResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/retrieval-requests/{retrieval_request_id}/messages": { "post": { "summary": "Send retrieval support message", "operationId": "submitRetrievalMessage", "tags": [ "Retrieval Requests" ], "description": "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).", "parameters": [ { "name": "retrieval_request_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Retrieval request ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalSupportMessageCreate" } } } }, "responses": { "200": { "description": "Message recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalSupportMessage" } } } }, "400": { "description": "Invalid message, email, preference, or attachment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing retrievals:write scope or support messaging disabled on the CMS connection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Retrieval request not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Submission already in progress (support_message_in_progress). Retry shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Submission failed; delivery may have succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "tags": [ { "name": "Cases", "description": "Case management operations" }, { "name": "Documents", "description": "Document upload and management" }, { "name": "Retrieval Requests", "description": "Medical record retrieval requests submitted to healthcare facilities" }, { "name": "Requestors", "description": "Multiple retrieval profiles within one organization" }, { "name": "Webhooks", "description": "Webhook registration and event notifications" } ] }