openapi: "3.0.0"

info:
  version: "1.0.0"
  title: "NextGen Office BulK FHIR API"
  description: "Our API is coded against the US Core Specification (FHIR Version: 4.0.0) \n\n https://hl7.org/fhir/us/core/STU4/ \n\n Note: This document is only for referring Bulk FHIR API."
  contact:
    email: "nextgen-office-api@nextgen.com"
externalDocs:
  description: "Find out more about NextGen Office FHIR API"
  url: "https://www.nextgen.com/products-and-services/nextgen-office"
servers:
  - url: https://fhir.meditouchehr.com/api/
    description: FHIR Base URL

paths:
  /bulkfhir/r4/$patient-search:
    get:
      security:
        - bearerAuth: []
      summary: Search Patients
      operationId: searchPatients
      tags:
        - Patient Search
      parameters:
        - name: page
          in: query
          schema:
            type: string
            example: 1
        - name: encDate
          in: query
          schema:
            type: string
            example: ge2025-01-01
        - name: patientChartNo
          in: query
          schema:
            type: string
            example: HF12345
      responses:
        '200':
          description: Successful retrieval of patients
        '400':
          description: Invalid request parameters
        '401':
          description: Unauthorized operation
        '403':
          description: Forbidden operation
        '404':
          description: No patients found
        '5XX':
          description: Unexpected error

  /bulkfhir/r4/Group:
    post:
      security:
        - bearerAuth: []
      summary: Create Group
      operationId: createGroup
      tags:
        - Group APIs
      requestBody:
        description: Request body for create Group API
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBulkFhirPatientGroup'
      responses:
        '201':
          description: Group created successfully
        '403':
          description: Forbidden operation (e.g., maximum limit reached)
        '422':
          description: Unprocessable entity (e.g., invalid patient IDs)
        '5XX':
          description: Unexpected error
    get:
      security:
        - bearerAuth: []
      summary: Retrieve all Groups
      operationId: getAllGroups
      tags:
        - Group APIs
      responses:
        '200':
          description: Groups retrieved successfully
        '403':
          description: Forbidden operation
        '404':
          description: No groups found
        '5XX':
          description: Unexpected error

  /bulkfhir/r4/Group/{id}:
    put:
      security:
        - bearerAuth: []
      summary: Update Group
      operationId: updateGroup
      tags:
        - Group APIs
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: 09208d49-32ca-45f5-a595-b1df2412543d
      requestBody:
        description: Request body for create Group API
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBulkFhirPatientGroup'
      responses:
        '200':
          description: Group updated successfully
        '403':
          description: Forbidden operation
        '404':
          description: Group not found
        '422':
          description: Unprocessable entity (e.g., invalid patient IDs)
        '5XX':
          description: Unexpected error
    delete:
      security:
        - bearerAuth: [ ]
      summary: Delete Group
      operationId: deleteGroup
      tags:
        - Group APIs
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: 09208d49-32ca-45f5-a595-b1df2412543d
      responses:
        '200':
          description: Group deleted successfully
        '403':
          description: Forbidden operation
        '404':
          description: Group not found
        '5XX':
          description: Unexpected error
    get:
      security:
        - bearerAuth: []
      summary: Retrieve Group
      operationId: getGroup
      tags:
        - Group APIs
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: 09208d49-32ca-45f5-a595-b1df2412543d
      responses:
        '200':
          description: Group retrieved successfully
        '401':
          description: Unauthorized operation
        '403':
          description: Forbidden operation
        '404':
          description: Group not found
        '5XX':
          description: Unexpected error

  /bulkfhir/r4/Group/{id}/$export:
    get:
      security:
        - bearerAuth: []
      summary: Group Export
      operationId: groupExport
      tags:
        - Export APIs
      description: "FHIR Operation to obtain a detailed set of FHIR resources of diverse resource types pertaining to all patients in specified Group."
      parameters:
        - $ref: "#/components/parameters/_GroupID"
        - in: header
          name: Prefer
          required: true
          schema:
            type: string
            example: respond-async
      responses:
        '202':
          description: Accepted
        '404':
          $ref: "#/components/responses/ResourceNotFound404"
        '401':
          $ref: "#/components/responses/ResourceNotAuthorized401"
        '429':
          $ref: "#/components/responses/TooManyRequests429"
        '5XX':
          description: Unexpected error
  /bulkfhir/r4/$export-poll-status:
    get:
      security:
        - bearerAuth: []
      summary: Poll Job Status
      operationId: pollJobStatus
      tags:
        - Export APIs
      description: "After a bulk data request has been started, the client MAY poll the status URL provided in the Content-Location header."
      parameters:
        - $ref: "#/components/parameters/_jobId"
      responses:
        '200':
          description: Export Completed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BulkDataStatusResponse"
        '202':
          description: Export in Progress
        '404':
          $ref: "#/components/responses/ResourceNotFound404"
        '401':
          $ref: "#/components/responses/ResourceNotAuthorized401"
        '5XX':
          description: Unexpected error
    delete:
      security:
        - bearerAuth: []
      summary: Delete Job
      operationId: deleteJob
      tags:
        - Export APIs
      description: "After a bulk data request has been started, a client MAY send a delete request to the URL provided in the Content-Location header to cancel the request."
      parameters:
        - $ref: "#/components/parameters/_jobId"
      responses:
        '202':
          description: Accepted
        '404':
          $ref: "#/components/responses/ResourceNotFound404"
        '401':
          $ref: "#/components/responses/ResourceNotAuthorized401"
        '5XX':
          description: Unexpected error

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  responses:
    Success200:
      description: Success
    ResourceNotFound404:
      description: Resource not found
    ResourceNotAuthorized401:
      description: Resource not authorized to be viewed by this user
    TooManyRequests429:
      description: Too Many Requests
  parameters:
    _jobId:
      description: The id of the resource
      name: "_jobId"
      in: "query"
      required: true
      schema:
        type: string
        example: 123456
    _GroupID:
      description: The id of the group
      name: "id"
      in: "path"
      required: true
      schema:
        type: string
        example: 09208d49-32ca-45f5-a595-b1df2412543d
  schemas:
    CreateBulkFhirPatientGroup:
      type: object
      required:
        - resourceType
        - patientIds
      properties:
        resourceType:
          type: string
        name:
          type: string
        patientIds:
          type: array
          items:
            type: string
      example:
        resourceType: "Group"
        name: "Diabetes Patients"
        patientIds: ["878792", "885904", "966958", "1008774", "1023533"]
    UpdateBulkFhirPatientGroup:
      type: object
      required:
        - resourceType
        - id
      properties:
        resourceType:
          type: string
        id:
          type: string
        name:
          type: string
        patientIdsToInclude:
          type: array
          items:
            type: string
        patientIdsToExclude:
          type: array
          items:
            type: string
      example:
        resourceType: "Group"
        id: "09208d49-32ca-45f5-a595-b1df2412543d"
        name: "Diabetes Patients with age greater than 50"
        patientIdsToInclude: [ "123457", "456789" ]
        patientIdsToExclude: [ "878792", "885904" ]
    BulkDataStatusResponse:
      type: object
      properties:
        transactionTime:
          type: string
          minLength: 1
        request:
          type: string
          minLength: 1
          description: id of the resource
        requiresAccessToken:
          type: boolean
          example: false
        output:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                minLength: 1
                description: The FHIR resource type that is contained in the file.
              url:
                type: string
                minLength: 1
                description: The path to the file.
        error:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                minLength: 1
                description: The FHIR resource type that is contained in the file.
              url:
                type: string
                minLength: 1
                description: The path to the file.