Datavant REST API

openapi: 3.1.0
info:
  title: Datavant REST 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'
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'
  /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'
  /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'
  /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}/queries:
    get:
      tags:
      - Order Queries
      summary: List all queries for an order
      description: Get a paginated list of all the queries associated with the specified order.
      operationId: list_queries_orders__order_id__queries_get
      parameters:
      - required: true
        schema:
          type: string
          title: Order Id
        name: order_id
        in: path
      - 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
      - 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_OrderQueryResponse_'
        '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'
    post:
      tags:
      - Order Queries
      summary: Add a query to an order
      description: Add a query to an existing order that has not yet been submitted.
      operationId: add_query_to_order_orders__order_id__queries_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:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderQueryRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderQueryResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '422':
          description: Order is not in 'draft' status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '404':
          description: Order does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
  /orders/{order_id}/queries/{query_id}:
    get:
      tags:
      - Order Queries
      summary: Get a query from an order
      description: Fetch the details of the specified query.
      operationId: get_query_in_order_orders__order_id__queries__query_id__get
      parameters:
      - required: true
        schema:
          type: string
          title: Order Id
        name: order_id
        in: path
      - required: true
        schema:
          type: string
          title: Query Id
        name: query_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/OrderQueryResponse'
        '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:
      - Order Queries
      summary: Update a query from an order
      description: Update an existing query that is part of an order that has yet to be submitted.
      operationId: update_query_in_order_orders__order_id__queries__query_id__put
      parameters:
      - required: true
        schema:
          type: string
          title: Order Id
        name: order_id
        in: path
      - required: true
        schema:
          type: string
          title: Query Id
        name: query_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/UpdateOrderQueryRequest'
        required: true
      responses:
        '204':
          description: Successful Response
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/comp

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