Datavant Orders API

openapi: 3.2.0
info:
  title: Datavant REST Orders API
  description: '

    Datavant''s REST API is a full-featured API built to facilitate programmatic access to our

    identified patient medical record retrieval capabilities. We provide predictable resource-oriented,

    JSON-encoded APIS protected by industry-standard OAuth2 ClientCredential authentication.

    '
  version: '2023-04-01'
servers:
- url: https://api.datavant.io/v2
security:
- oauth2: []
tags:
- name: Orders
  description: '

    An order is the parent container for incoming queries. An order contains one or more queries along

    with other identifying information (e.g., type, reason, etc.)

    '
paths:
  /orders/:
    get:
      tags:
      - Orders
      summary: List all orders
      description: 'Get a paginated list of all orders for the given tenant,

        excluding deleted and prematch orders'
      operationId: list_orders_orders__get
      parameters:
      - required: false
        schema:
          type: integer
          maximum: 100.0
          minimum: 1.0
          title: Limit
          default: 50
        name: limit
        in: query
      - required: false
        schema:
          type: integer
          minimum: 0.0
          title: Offset
          default: 0
        name: offset
        in: query
      - required: false
        schema:
          type: string
          title: Sort By
        name: sort_by
        in: query
      - required: false
        schema:
          type: string
          title: Sort Dir
        name: sort_dir
        in: query
      - required: false
        schema:
          type: string
          title: Project Name
        name: project_name
        in: query
      - required: false
        schema:
          type: string
          title: Order Name
        name: order_name
        in: query
      - required: false
        schema:
          type: string
          title: Secondary Reason
        name: secondary_reason
        in: query
      - required: false
        schema:
          type: string
          title: Status
        name: status
        in: query
      - description: Version of the Orders API to use with this call
        required: false
        schema:
          type: string
          title: Version-Datavant
          description: Version of the Orders API to use with this call
          default: '2023-04-01'
        name: version-datavant
        in: header
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonApiPage_OrderResponse_'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
    post:
      tags:
      - Orders
      summary: Create an order
      description: 'Create an Order.

        Returns HTTP_409_CONFLICT if order with the same ID already exists for the given customer ID.'
      operationId: create_order_orders__post
      parameters:
      - description: Version of the Orders API to use with this call
        required: false
        schema:
          type: string
          title: Version-Datavant
          description: Version of the Orders API to use with this call
          default: '2023-04-01'
        name: version-datavant
        in: header
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '409':
          description: Order with specified ID already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
  /orders/order:
    get:
      summary: Get an order
      description: 'Fetch the details of a specific order.


        Either ''id'' or ''uuid'' must be provided.'
      operationId: get_order_by_specific_id_orders_order_get
      parameters:
      - required: false
        schema:
          type: string
          title: Id
          default: ''
        name: id
        in: query
      - required: false
        schema:
          type: string
          title: Uuid
          default: ''
        name: uuid
        in: query
      - description: Version of the Orders API to use with this call
        required: false
        schema:
          type: string
          title: Version-Datavant
          description: Version of the Orders API to use with this call
          default: '2023-04-01'
        name: version-datavant
        in: header
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
      tags:
      - Orders
  /orders/{order_id}:
    get:
      tags:
      - Orders
      summary: Get an order
      description: Fetch the details of a specific order.
      operationId: get_order_orders__order_id__get
      parameters:
      - required: true
        schema:
          type: string
          title: Order Id
        name: order_id
        in: path
      - required: false
        schema:
          type: boolean
          title: Queries
          default: true
        name: queries
        in: query
      - description: Version of the Orders API to use with this call
        required: false
        schema:
          type: string
          title: Version-Datavant
          description: Version of the Orders API to use with this call
          default: '2023-04-01'
        name: version-datavant
        in: header
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
    put:
      tags:
      - Orders
      summary: Update an order
      description: Modify an order that has not yet been submitted.
      operationId: update_order_orders__order_id__put
      parameters:
      - required: true
        schema:
          type: string
          title: Order Id
        name: order_id
        in: path
      - description: Version of the Orders API to use with this call
        required: false
        schema:
          type: string
          title: Version-Datavant
          description: Version of the Orders API to use with this call
          default: '2023-04-01'
        name: version-datavant
        in: header
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOrderRequest'
        required: true
      responses:
        '204':
          description: Successful Response
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
  /orders/order/validation/stats:
    get:
      summary: Get an order's basic validation results
      description: 'Fetch the basic validation results for a specific order


        Either ''id'' or ''uuid'' must be provided.'
      operationId: get_order_validation_results_by_specific_id_orders_order_validation_stats_get
      parameters:
      - required: false
        schema:
          type: string
          title: Id
          default: ''
        name: id
        in: query
      - required: false
        schema:
          type: string
          title: Uuid
          default: ''
        name: uuid
        in: query
      - description: Version of the Orders API to use with this call
        required: false
        schema:
          type: string
          title: Version-Datavant
          description: Version of the Orders API to use with this call
          default: '2023-04-01'
        name: version-datavant
        in: header
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderValidationResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
      tags:
      - Orders
  /orders/{order_id}/validation/stats:
    get:
      tags:
      - Orders
      summary: Get an order's basic validation results
      description: Fetch the basic validation results for a specific order.
      operationId: get_order_validation_results_orders__order_id__validation_stats_get
      parameters:
      - required: true
        schema:
          type: string
          title: Order Id
        name: order_id
        in: path
      - description: Version of the Orders API to use with this call
        required: false
        schema:
          type: string
          title: Version-Datavant
          description: Version of the Orders API to use with this call
          default: '2023-04-01'
        name: version-datavant
        in: header
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderValidationResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
  /orders/{order_uuid}/validation/report:
    get:
      tags:
      - Orders
      summary: Get an order validation report
      description: Fetch a validation report for a specific order.
      operationId: get_order_validation_report_orders__order_uuid__validation_report_get
      parameters:
      - required: true
        schema:
          type: string
          title: Order Uuid
        name: order_uuid
        in: path
      - description: Version of the Orders API to use with this call
        required: false
        schema:
          type: string
          title: Version-Datavant
          description: Version of the Orders API to use with this call
          default: '2023-04-01'
        name: version-datavant
        in: header
      responses:
        '200':
          description: Successful Response
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
  /orders/{order_uuid}/validation/supplemental-data-report:
    get:
      tags:
      - Orders
      summary: Get an order supplemental data validation report
      description: Fetch the validation report for supplemental data for a specific order.
      operationId: get_order_supplemental_data_validation_report_orders__order_uuid__validation_supplemental_data_report_get
      parameters:
      - required: true
        schema:
          type: string
          title: Order Uuid
        name: order_uuid
        in: path
      - description: Version of the Orders API to use with this call
        required: false
        schema:
          type: string
          title: Version-Datavant
          description: Version of the Orders API to use with this call
          default: '2023-04-01'
        name: version-datavant
        in: header
      responses:
        '200':
          description: Successful Response
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
  /orders/{order_uuid}/error-and-warning-counts:
    get:
      tags:
      - Orders
      summary: Get grouped order validation errors and varnings with counts
      operationId: get_order_errors_and_warnings_orders__order_uuid__error_and_warning_counts_get
      parameters:
      - required: true
        schema:
          type: string
          title: Order Uuid
        name: order_uuid
        in: path
      - description: Version of the Orders API to use with this call
        required: false
        schema:
          type: string
          title: Version-Datavant
          description: Version of the Orders API to use with this call
          default: '2023-04-01'
        name: version-datavant
        in: header
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
  /orders/{order_id}/reporting/retrievals:
    get:
      summary: Get reporting for order retrievals
      description: Fetch retrieval numbers for order.
      operationId: get_order_retrievals_reporting_data_orders__order_id__reporting_retrievals_get
      parameters:
      - required: true
        schema:
          type: string
          title: Order Id
        name: order_id
        in: path
      - required: false
        schema:
          type: boolean
          title: Breakdown
          default: true
        name: breakdown
        in: query
      - required: false
        schema:
          type: boolean
          title: Snowflake
          default: false
        name: snowflake
        in: query
      - description: Version of the Orders API to use with this call
        required: false
        schema:
          type: string
          title: Version-Datavant
          description: Version of the Orders API to use with this call
          default: '2023-04-01'
        name: version-datavant
        in: header
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderReportingResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
      tags:
      - Orders
  /orders/{order_uuid}/cancel:
    post:
      tags:
      - Orders
      summary: Cancel an order
      description: Cancel an order that has not yet been submitted.
      operationId: cancel_order_orders__order_uuid__cancel_post
      parameters:
      - required: true
        schema:
          type: string
          title: Order Uuid
        name: order_uuid
        in: path
      - description: Version of the Orders API to use with this call
        required: false
        schema:
          type: string
          title: Version-Datavant
          description: Version of the Orders API to use with this call
          default: '2023-04-01'
        name: version-datavant
        in: header
      responses:
        '204':
          description: Successful Response
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
  /orders/{order_id}/close-request:
    post:
      tags:
      - Orders
      summary: Deal with an order close request
      description: 'Handle an order close request.


        1. Set the order status to ''close_in_progress''.

        2. Set the ''close_request_at'' timestamp in the order''s metadata.

        3. Publish an SNS message that the order status has changed to ''close_in_progress''.


        The current subscribers to this topic are the retrieval project close worker and the delivery order status updated worker.'
      operationId: close_order_orders__order_id__close_request_post
      parameters:
      - required: true
        schema:
          type: string
          title: Order Id
        name: order_id
        in: path
      - description: Version of the Orders API to use with this call
        required: false
        schema:
          type: string
          title: Version-Datavant
          description: Version of the Orders API to use with this call
          default: '2023-04-01'
        name: version-datavant
        in: header
      responses:
        '204':
          description: Successful Response
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
  /orders/{order_id}/roster:
    post:
      tags:
      - Orders
      summary: Attach a roster to an order
      description: Attach a roster to an order.
      operationId: attach_roster_orders__order_id__roster_post
      parameters:
      - required: true
        schema:
          type: string
          title: Order Id
        name: order_id
        in: path
      - description: Version of the Orders API to use with this call
        required: false
        schema:
          type: string
          title: Version-Datavant
          description: Version of the Orders API to use with this call
          default: '2023-04-01'
        name: version-datavant
        in: header
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_attach_roster_orders__order_id__roster_post'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
  /orders/{order_id}/supplemental-data:
    post:
      tags:
      - Orders
      summary: Upload supplemental data to an order
      description: 'Upload supplemental data to an order.


        This includes values (such as SDOS) that are needed for request fulfillment but not routing.

        It should be uploaded after the raw rows from the request file (start file) have been copied from

        staged_order_row to order_queries and encounter and before requests are sent out to retrieval methods.'
      operationId: attach_supplemental_data_orders__order_id__supplemental_data_post
      parameters:
      - required: true
        schema:
          type: string
          title: Order Id
        name: order_id
        in: path
      - description: Version of the Orders API to use with this call
        required: false
        schema:
          type: string
          title: Version-Datavant
          description: Version of the Orders API to use with this call
          default: '2023-04-01'
        name: version-datavant
        in: header
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_attach_supplemental_data_orders__order_id__supplemental_data_post'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
  /orders/{order_id}/dispatch:
    post:
      tags:
      - Orders
      summary: Dispatch an order
      description: Submit an order for dispatch through UI
      operationId: dispatch_order_orders__order_id__dispatch_post
      parameters:
      - required: true
        schema:
          type: string
          title: Order Id
        name: order_id
        in: path
      - description: Version of the Orders API to use with this call
        required: false
        schema:
          type: string
          title: Version-Datavant
          description: Version of the Orders API to use with this call
          default: '2023-04-01'
        name: version-datavant
        in: header
      responses:
        '204':
          description: Successful Response
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
  /orders/{order_id}/submit:
    post:
      tags:
      - Orders
      summary: Submit an order
      description: Submit an order for dispatch and record retrieval
      operationId: submit_order_orders__order_id__submit_post
      parameters:
      - required: true
        schema:
          type: string
          title: Order Id
        name: order_id
        in: path
      - description: Version of the Orders API to use with this call
        required: false
        schema:
          type: string
          title: Version-Datavant
          description: Version of the Orders API to use with this call
          default: '2023-04-01'
        name: version-datavant
        in: header
      responses:
        '204':
          description: Successful Response
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
  /orders/{order_id}/start-record-retrieval:
    put:
      tags:
      - Orders
      summary: Begin dispatching instructions
      operationId: dispatch_instructions_orders__order_id__start_record_retrieval_put
      parameters:
      - required: true
        schema:
          type: string
          title: Order Id
        name: order_id
        in: path
      - description: Version of the Orders API to use with this call
        required: false
        schema:
          type: string
          title: Version-Datavant
          description: Version of the Orders API to use with this call
          default: '2023-04-01'
        name: version-datavant
        in: header
      responses:
        '204':
          description: Successful Response
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
components:
  schemas:
    ChartPackage:
      enum:
      - Default
      title: ChartPackage
      description: Packages referring to pre-configured bundles of chart components.
    ChartFinderConfiguration:
      properties:
        coding:
          type: boolean
          title: Coding
          description: Does this client use Datavant for coding?
        audit_type:
          type: integer
          title: Audit Type
          description: Audit type for this project.
        review_type:
          anyOf:
          - type: string
          - type: integer
          title: Audit Type
          description: Audit type for this project.
        idsb_handling_qa:
          type: integer
          enum:
          - 0
          - 1
          title: IDSB Handling QA
          description: IDSB Handling QA for this project.
        idsb_retrieving:
          type: integer
          enum:
          - 0
          - 1
          title: IDSB Retrieving
          description: IDSB directly using some retrieval methods without CF for this project.
        idsb_retrieving_embedded:
          type: integer
          enum:
          - 0
          - 1
          title: IDSB Retrieving Embedded
          description: IDSB directly retrieving for embedded retrieval methods for this project.
        account_manager_id:
          type: integer
          title: Account Manager ID
          description: Account Manager ID for this project.
      type: object
      title: ChartFinderConfiguration
      description: 'A custom BaseModel with the eventual goal of populating inheriting models with the value property

        of enums rather than the raw enum.


        For now this is set to False (default setting) and we only set enum values to true within the

        models that have enums we know we need to use the values for.'
    ConnectionsReport:
      properties:
        date_of_first_retrieval:
          type: string
          format: date-time
          title: Date Of First Retrieval
          description: Time of the first chart retrieval.
        date_of_latest_retrieval:
          type: string
          format: date-time
          title: Date Of Latest Retrieval
          description: Time of the last chart retrieval.
        counts:
          items:
            $ref: '#/components/schemas/ConnectionCounts'
          type: array
          title: Counts
          description: List of charts retrieved by source.
      type: object
      required:
      - date_of_first_retrieval
      - date_of_latest_retrieval
      - counts
      title: ConnectionsReport
      description: 'A custom BaseModel with the eventual goal of populating inheriting models with the value property

        of enums rather than the raw enum.


        For now this is set to False (default setting) and we only set enum values to true within the

        models that have enums we know we need to use the values for.'
    EachDocumentDeliveryOptions:
      properties:
        delivery_frequency_sub_option:
          type: 'null'
          title: Delivery Frequency Sub Option
        delivery_frequency:
          type: string
          enum:
          - each_document
          title: Delivery Frequency
      type: object
      required:
      - delivery_frequency_sub_option
      - delivery_frequency
      title: EachDocumentDeliveryOptions
      description: 'A custom BaseModel with the eventual goal of populating inheriting models with the value property

        of enums rather than the raw enum.


        For now this is set to False (default setting) and we only set enum values to true within the

        models that have enums we know we need to use the values for.'
    RetrievalSources:
      type: string
      enum:
      - api
      - embedded_manual
      - nonembedded_manual
      - athena
      - healthjump
      - mock_retrieval
      - moxe
      - office_ally
      - particle
      - ses
      - share_arkansas
      - sidus
      - veradigm
      - vim
      - iatric
      - c3hie
      - ghhc
      - healow
      - mdland
      title: RetrievalSources
      description: An enumeration.
    DailyDeliveryOptions:
      properties:
        delivery_frequency_sub_option:
          type: 'null'
          title: Delivery Frequency Sub Option
        delivery_frequency:
          type: string
          enum:
          - daily
          title: Delivery Frequency
      type: object
      required:
      - delivery_frequency_sub_option
      - delivery_frequency
      title: DailyDeliveryOptions
      description: 'A custom BaseModel with the eventual goal of populating inheriting models with the value property

        of enums rather than the raw enum.


        For now this is set to False (default setting) and we only set enum values to true within the

        models that have enums we know we need to use the values for.'
    StructuredDataExtractionReportConfiguration:
      properties:
        deli

# --- truncated at 32 KB (118 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/datavant/refs/heads/main/openapi/datavant-orders-api-openapi.yml