> ## 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.

# Get retrieval request

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



## OpenAPI

````yaml GET /v2/retrieval-requests/{retrieval_request_id}
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/retrieval-requests/{retrieval_request_id}:
    get:
      tags:
        - Retrieval Requests
      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
      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'
components:
  schemas:
    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
    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
    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.
    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` — step happened; `current` — the request is here now;
            `pending` — standard step not reached yet; `skipped` — 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` — your firm still needs to respond;
                `answered` — your firm responded; `resolved` — 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
    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'
    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.
    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.
    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.
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        API key authentication. Use format: `Authorization: Bearer
        tavrn_sk_live_...`

````