openapi: 3.2.0
info:
  title: Datavant REST Documents 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: Documents
  description: '

    Interact with the various documents that are collected and/or generated by Datavant through the identified

    patient record retrieval process including patient medical records and supporting documents.

    '
paths:
  /documents:
    get:
      tags:
      - Documents
      summary: List all documents
      description: Get a paginated list of all the documents associated with the specified order or query.
      operationId: list_documents_documents_get
      parameters:
      - required: false
        schema:
          type: string
          maxLength: 100
          minLength: 1
          pattern: ^[a-zA-Z0-9_-]+$
          title: Order Id
        name: order_id
        in: query
      - required: false
        schema:
          type: string
          format: uuid4
          title: Order Uuid
        name: order_uuid
        in: query
      - required: false
        schema:
          type: string
          maxLength: 100
          minLength: 1
          pattern: ^[a-zA-Z0-9_-]+$
          title: Query Id
        name: query_id
        in: query
      - required: false
        schema:
          type: string
          format: uuid4
          title: Query Uuid
        name: query_uuid
        in: query
      - required: false
        schema:
          type: string
          format: uuid4
          title: Chase Uuid
        name: chase_uuid
        in: query
      - 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_DocumentResponse_'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
  /documents/{document_uuid}:
    get:
      tags:
      - Documents
      summary: Download a document
      description: Download the specified document.
      operationId: download_document_documents__document_uuid__get
      parameters:
      - required: true
        schema:
          type: string
          title: Document Uuid
        name: document_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: Invalid document UUID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '404':
          description: Document does not exist for the tenant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
        '501':
          description: Document exists in an unsupported document store. Please contact tech support for assistance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorHTTPResponse'
components:
  schemas:
    Links:
      properties:
        first:
          type: string
          title: First
          example: /api/v1/users?limit=1&offset1
        last:
          type: string
          title: Last
          example: /api/v1/users?limit=1&offset1
        self:
          type: string
          title: Self
          example: /api/v1/users?limit=1&offset1
        next:
          type: string
          title: Next
          example: /api/v1/users?limit=1&offset1
        prev:
          type: string
          title: Prev
          example: /api/v1/users?limit=1&offset1
      type: object
      title: Links
    DocumentType:
      enum:
      - chart
      - provider_packet
      - health_plan_letter
      - request_letter
      - letter_of_representation
      - patient_authorization
      - request_file
      - supplemental_data
      - merge_report
      - quality_review_guide
      - provider_packet_additional_document
      title: DocumentType
      description: The type of document.
    JsonApiPage_DocumentResponse_:
      properties:
        data:
          items:
            $ref: '#/components/schemas/DocumentResponse'
          type: array
          title: Data
        total:
          type: integer
          minimum: 0.0
          title: Total
        limit:
          type: integer
          minimum: 1.0
          title: Limit
        offset:
          type: integer
          minimum: 0.0
          title: Offset
        links:
          $ref: '#/components/schemas/Links'
        unfiltered_total:
          type: integer
          title: Unfiltered Total
      type: object
      required:
      - data
      - total
      - links
      title: JsonApiPage[DocumentResponse]
      description: JSON:API 1.0 specification says that result key should be a `data`.
    DocumentResponse:
      properties:
        uuid:
          type: string
          title: UUID4
          description: Unique identifier for the object.
        type:
          allOf:
          - $ref: '#/components/schemas/DocumentType'
          description: The type of document
        metadata:
          type: object
          title: Metadata
          description: Miscellaneous metadata associated with the document
        created_at:
          type: string
          format: date-time
          title: Date Created
          description: The ISO8601 formatted timestamp for when the object was created.
        updated_at:
          type: string
          format: date-time
          title: Date Last Updated
          description: The ISO8601 formatted timestamp for when the object was last updated.
        links:
          $ref: '#/components/schemas/DocumentLinks'
      type: object
      required:
      - uuid
      - type
      - metadata
      - created_at
      title: DocumentResponse
      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.'
    DocumentLinks:
      properties:
        download:
          type: string
          maxLength: 2083
          minLength: 1
          format: uri
          title: Download
      type: object
      required:
      - download
      title: DocumentLinks
      description: Link to download the document.
    ErrorHTTPResponse:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/Error'
          type: array
          title: Errors
          description: List of all errors
      type: object
      required:
      - errors
      title: ErrorHTTPResponse
      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.'
    Error:
      properties:
        code:
          type: string
          title: Code
          description: Error code specifiying type of error
        message:
          type: string
          title: Message
          description: Human readable message describing error
        params:
          items: {}
          type: array
          title: Params
          description: The parameters involved in the error
      type: object
      required:
      - code
      - message
      title: Error
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.datavant.io/v2/oauth2/token
          refreshUrl: https://api.datavant.io/v2/oauth2/token
          scopes: {}