AdvancedMD Document Reference API

openapi: 3.2.0
info:
  version: 6.1.0
  title: FHIR Single API - US Core 6.1.0 Document Reference API
  description: Fast Healthcare Interoperability Resources (HL7® FHIR®, pronounced "Fire") defines a set of "Resources" that represent granular clinical concepts.
  x-fhir-version: 4.0.1
  x-us-core-version: 6.1.0
servers:
- url: https://providerapi.advancedmd.com/v1/r4
security:
- bearerAuth: []
tags:
- name: Document Reference
paths:
  /DocumentReference:
    get:
      tags:
      - Document Reference
      description: 'This interaction searches a set of DocumentReferences based on some filter criteria. Search interactions take a series of query parameters for a GET.

        📘 FHIR documentation for DocumentReference.


        🛡️ **Authorization behavior:**

        - **Patients** (using `patient/*.read` scope) can access only their own resources.

        - **Practitioners** (using `patient/*.read` scope) can access to only one assigned patient.

        - **Practitioners** (using `user/*.read` scope) must provide the `patient` query parameter to access another patient''s data.'
      parameters:
      - name: patient
        in: query
        description: Who/what is the subject of the document
        schema:
          type: string
        examples:
          patient_id:
            summary: Logical patient id
            value: '6077169'
          patient_reference:
            summary: Relative Patient reference
            value: Patient/6077169
      - name: _id
        in: query
        description: Logical id of the document reference
        schema:
          type: string
        example: 153649915
      - name: type
        in: query
        description: Kind of document (LOINC if possible)
        schema:
          type: string
        example: 34133-9
      - name: category
        in: query
        description: Categorization of document
        schema:
          type: string
        example: clinical-note
      - name: date
        in: query
        description: When this document reference was created
        schema:
          type: string
          format: date
        example: '2024-06-01'
      responses:
        '200':
          description: Success
          content:
            application/fhir+json;charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DocumentReference'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Get document reference
      x-summary-source: derived
      operationId: getDocumentReference
      x-operation-id-source: derived
  /DocumentReference/{id}:
    get:
      tags:
      - Document Reference
      description: 'This interaction searches DocumentReference based on document reference id.Search interactions take document reference id in path for a GET.

        📘 FHIR documentation for DocumentReference.


        🛡️ **Authorization behavior:**

        - **Patients** (using `patient/*.read` scope) can access only their own resources.

        - **Practitioners** (using `patient/*.read` scope) can access to only one assigned patient.

        - **Practitioners** (using `user/*.read` scope) must provide the `patient` query parameter to access another patient''s data.'
      parameters:
      - name: id
        in: path
        description: The logical resource id associated with the Resource.
        required: true
        schema:
          type: integer
          example: 153649915
      - name: patient
        in: query
        description: Patient ID to filter the search.
        schema:
          type: integer
          example: 6077169
      responses:
        '200':
          description: Success
          content:
            application/fhir+json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/DocumentReference'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Get document reference by id
      x-summary-source: derived
      operationId: getDocumentReferenceById
      x-operation-id-source: derived
  /DocumentReference/$docref:
    get:
      tags:
      - Document Reference
      description: 'This operation returns references to documents related to a patient and aligns to the US Core Fetch DocumentReference operation.

        📄 US Core $docref operation.


        🛡️ **Authorization behavior:**

        - **Patients** (using `patient/*.read` scope) can access only their own resources.

        - **Practitioners** (using `patient/*.read` scope) can access to only one assigned patient.

        - **Practitioners** (using `user/*.read` scope) must provide the `patient` query parameter to access another patient''s data.'
      operationId: DocumentReferenceFetchDocref
      parameters:
      - name: patient
        in: query
        required: true
        description: The id of the patient resource.
        schema:
          type: integer
        example: 6077169
      - name: start
        in: query
        description: Start of the care date range for matching documents.
        schema:
          type: string
          format: date-time
        example: '2024-01-01T00:00:00Z'
      - name: end
        in: query
        description: End of the care date range for matching documents.
        schema:
          type: string
          format: date-time
        example: '2024-12-31T23:59:59Z'
      - name: type
        in: query
        description: Document type code such as the LOINC code for CCD.
        schema:
          type: string
        example: 34133-9
      - name: on-demand
        in: query
        description: Whether to request only on-demand documents.
        schema:
          type: boolean
        example: false
      - name: profile
        in: query
        description: Canonical profile URL used to request documents for a specific profile.
        schema:
          type: string
        example: http://hl7.org/fhir/us/core/StructureDefinition/us-core-documentreference
      responses:
        '200':
          description: Searchset bundle containing DocumentReference resources.
          content:
            application/fhir+json;charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DocumentReference'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Document reference fetch docref
      x-summary-source: derived
  /DocumentReference/_search:
    post:
      tags:
      - Document Reference
      description: 'This interaction searches a set of DocumentReferences based on some filter criteria. Search interactions take a series of parameters of name''''=''''value pairs encoded as an application/x-www-form-urlencoded submission for a POST.

        📘 FHIR documentation for DocumentReference.


        🛡️ **Authorization behavior:**

        - **Patients** (using `patient/*.read` scope) can access only their own resources.

        - **Practitioners** (using `patient/*.read` scope) can access to only one assigned patient.

        - **Practitioners** (using `user/*.read` scope) must provide the `patient` parameter (in the request body) to access another patient''s data.'
      operationId: DocumentReferences Search using POST
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                patient:
                  type: integer
                  description: Who/what is the subject of the document
                  example: 6077169
                _id:
                  type: string
                  description: Logical id of the document reference
                  example: 153649915
                type:
                  type: string
                  description: Kind of document (LOINC if possible)
                  example: 34133-9
                category:
                  type: string
                  description: Categorization of document
                  example: clinical-note
                date:
                  type: string
                  format: date
                  description: When this document reference was created
                  example: '2024-06-01'
              required:
              - patient
      responses:
        '200':
          description: DocumentReference bundle
          content:
            application/fhir+json;charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DocumentReference'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Document references search using POST
      x-summary-source: derived
components:
  schemas:
    Error:
      required:
      - text
      - issue
      type: object
      properties:
        resourceType:
          minLength: 1
          type: string
        text:
          required:
          - div
          - status
          type: object
          properties:
            status:
              minLength: 1
              type: string
            div:
              minLength: 1
              type: string
        issue:
          type: array
          items:
            required:
            - severity
            - code
            - diagnostics
            type: object
            properties:
              severity:
                minLength: 1
                type: string
              code:
                minLength: 1
                type: string
              diagnostics:
                minLength: 1
                type: string
    DocumentReference:
      x-us-core-profile: http://hl7.org/fhir/us/core/StructureDefinition/us-core-documentreference
      required:
      - authenticator
      - author
      - category
      - contained
      - content
      - context
      - custodian
      - date
      - description
      - docStatus
      - id
      - identifier
      - masterIdentifier
      - meta
      - relatesTo
      - resourceType
      - securityLabel
      - status
      - subject
      - text
      - type
      type: object
      properties:
        resourceType:
          minLength: 1
          type: string
        id:
          minLength: 1
          type: string
        text:
          required:
          - div
          - status
          type: object
          properties:
            status:
              minLength: 1
              type: string
            div:
              minLength: 1
              type: string
        contained:
          minItems: 1
          uniqueItems: true
          type: array
          items:
            required:
            - id
            - resourceType
            type: object
            properties:
              resourceType:
                minLength: 1
                type: string
              id:
                minLength: 1
                type: string
              name:
                minItems: 1
                uniqueItems: true
                type: array
                items:
                  required:
                  - family
                  type: object
                  properties:
                    family:
                      minLength: 1
                      type: string
                    given:
                      type: array
                      items:
                        type: object
                        properties: {}
        masterIdentifier:
          description: Master identifier assigned to this document by the publishing or source document system.
          required:
          - system
          - value
          type: object
          properties:
            system:
              description: Namespace or URI that defines the master identifier value.
              minLength: 1
              type: string
            value:
              description: Master identifier value unique within the stated system.
              minLength: 1
              type: string
        identifier:
          description: Additional business identifiers associated with this document reference.
          minItems: 1
          uniqueItems: true
          type: array
          items:
            description: Identifier with a namespace in `system` and a resource-specific value in `value`.
            required:
            - system
            - value
            type: object
            properties:
              system:
                description: Namespace or URI that defines the identifier value.
                minLength: 1
                type: string
              value:
                description: Identifier value unique within the stated system.
                minLength: 1
                type: string
        status:
          minLength: 1
          type: string
        docStatus:
          minLength: 1
          type: string
        type:
          required:
          - coding
          type: object
          properties:
            coding:
              minItems: 1
              uniqueItems: true
              type: array
              items:
                required:
                - code
                - display
                - system
                type: object
                properties:
                  system:
                    minLength: 1
                    type: string
                  code:
                    minLength: 1
                    type: string
                  display:
                    minLength: 1
                    type: string
        category:
          minItems: 1
          uniqueItems: true
          type: array
          items:
            type: object
            properties:
              coding:
                minItems: 1
                uniqueItems: true
                type: array
                items:
                  required:
                  - code
                  - display
                  - system
                  type: object
                  properties:
                    system:
                      minLength: 1
                      type: string
                    code:
                      minLength: 1
                      type: string
                    display:
                      minLength: 1
                      type: string
        subject:
          required:
          - reference
          type: object
          properties:
            reference:
              minLength: 1
              type: string
        date:
          minLength: 1
          type: string
        author:
          minItems: 1
          uniqueItems: true
          type: array
          items:
            required:
            - reference
            type: object
            properties:
              reference:
                minLength: 1
                type: string
        authenticator:
          required:
          - reference
          type: object
          properties:
            reference:
              minLength: 1
              type: string
        custodian:
          required:
          - reference
          type: object
          properties:
            reference:
              minLength: 1
              type: string
        relatesTo:
          minItems: 1
          uniqueItems: true
          type: array
          items:
            required:
            - code
            type: object
            properties:
              code:
                minLength: 1
                type: string
              target:
                required:
                - reference
                type: object
                properties:
                  reference:
                    minLength: 1
                    type: string
        description:
          minLength: 1
          type: string
        securityLabel:
          minItems: 1
          uniqueItems: true
          type: array
          items:
            type: object
            properties:
              coding:
                minItems: 1
                uniqueItems: true
                type: array
                items:
                  required:
                  - code
                  - display
                  - system
                  type: object
                  properties:
                    system:
                      minLength: 1
                      type: string
                    code:
                      minLength: 1
                      type: string
                    display:
                      minLength: 1
                      type: string
        content:
          minItems: 1
          uniqueItems: true
          type: array
          items:
            type: object
            properties:
              attachment:
                required:
                - contentType
                - creation
                - hash
                - language
                - size
                - title
                - url
                type: object
                properties:
                  contentType:
                    minLength: 1
                    type: string
                  language:
                    minLength: 1
                    type: string
                  url:
                    minLength: 1
                    type: string
                  size:
                    type: number
                  hash:
                    minLength: 1
                    type: string
                  title:
                    minLength: 1
                    type: string
                  creation:
                    minLength: 1
                    type: string
              format:
                required:
                - code
                - display
                - system
                type: object
                properties:
                  system:
                    minLength: 1
                    type: string
                  code:
                    minLength: 1
                    type: string
                  display:
                    minLength: 1
                    type: string
        context:
          required:
          - encounter
          - event
          - facilityType
          - period
          - practiceSetting
          - related
          - sourcePatientInfo
          type: object
          properties:
            encounter:
              minItems: 1
              uniqueItems: true
              type: array
              items:
                required:
                - reference
                type: object
                properties:
                  reference:
                    minLength: 1
                    type: string
            event:
              minItems: 1
              uniqueItems: true
              type: array
              items:
                type: object
                properties:
                  coding:
                    minItems: 1
                    uniqueItems: true
                    type: array
                    items:
                      required:
                      - code
                      - display
                      - system
                      type: object
                      properties:
                        system:
                          minLength: 1
                          type: string
                        code:
                          minLength: 1
                          type: string
                        display:
                          minLength: 1
                          type: string
            period:
              required:
              - end
              - start
              type: object
              properties:
                start:
                  minLength: 1
                  type: string
                end:
                  minLength: 1
                  type: string
            facilityType:
              required:
              - coding
              type: object
              properties:
                coding:
                  minItems: 1
                  uniqueItems: true
                  type: array
                  items:
                    required:
                    - code
                    - display
                    - system
                    type: object
                    properties:
                      system:
                        minLength: 1
                        type: string
                      code:
                        minLength: 1
                        type: string
                      display:
                        minLength: 1
                        type: string
            practiceSetting:
              required:
              - coding
              type: object
              properties:
                coding:
                  minItems: 1
                  uniqueItems: true
                  type: array
                  items:
                    required:
                    - code
                    - display
                    - system
                    type: object
                    properties:
                      system:
                        minLength: 1
                        type: string
                      code:
                        minLength: 1
                        type: string
                      display:
                        minLength: 1
                        type: string
            sourcePatientInfo:
              required:
              - reference
              type: object
              properties:
                reference:
                  minLength: 1
                  type: string
            related:
              minItems: 1
              uniqueItems: true
              type: array
              items:
                required:
                - reference
                type: object
                properties:
                  reference:
                    minLength: 1
                    type: string
                  identifier:
                    required:
                    - system
                    - value
                    type: object
                    properties:
                      system:
                        minLength: 1
                        type: string
                      value:
                        minLength: 1
                        type: string
        meta:
          required:
          - tag
          type: object
          properties:
            tag:
              minItems: 1
              uniqueItems: true
              type: array
              items:
                required:
                - code
                - display
                - system
                type: object
                properties:
                  system:
                    minLength: 1
                    type: string
                  code:
                    minLength: 1
                    type: string
                  display:
                    minLength: 1
                    type: string
      description: ''
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
externalDocs:
  description: HL7 FHIR US Core IG STU 6.1.0
  url: https://hl7.org/fhir/us/core/STU6.1/