> ## Documentation Index > Fetch the complete documentation index at: https://docs.tavrn.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create retrieval request > 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. ## OpenAPI ````yaml POST /v2/cases/{case_id}/retrieval-requests 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: [] 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 paths: /v2/cases/{case_id}/retrieval-requests: post: tags: - Retrieval Requests 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 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 — 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' components: schemas: 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 — 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 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. 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. 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 — 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 — many facilities verify identity against DOB, SSN last-4, or address before releasing records. 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. 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 — 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. 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 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 — medical, billing, imaging — 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 — contact Tavrn support to enable. 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. 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. 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. 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 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: >- API key authentication. Use format: `Authorization: Bearer tavrn_sk_live_...` ````