Best Practice Software Sites API

openapi: 3.2.0
info:
  version: 26.619.10213
  title: Halo Cloud API for Integrators Sites API
  contact:
    name: Halo Connect Support
    email: support@haloconnect.io
  license:
    name: Copyright © Halo Connect 2023
    url: http://haloconnect.io
  x-logo:
    url: https://20496383.fs1.hubspotusercontent-na1.net/hubfs/20496383/halo_logo%20(1).png
    altText: Halo Connect Logo
  description: '## Introduction

    This API reference documents the endpoints available to integrators using the Halo Connect Cloud API. It covers:


    - **Sites** – Retrieve site metadata and onboarding information

    - **SQL Passthrough** – Execute SQL queries against practice databases

    - **FHIR** – Query practice data using FHIR resources

    - **Registered Queries** – Execute recurring SQL queries against practice databases


    For more information about Halo Connect, visit our [website](https://haloconnect.io) or [blog](https://haloconnect.io/blog).


    ## Prerequisites


    All API endpoints require an active pairing with the target site. Use the [Pair with a site](#operation/Integrator_PairSite) endpoint to establish access before making queries.


    ## Definitions


    For detailed documentation and guides, see our [documentation portal](https://docs.haloconnect.io).


    - **Site:** An instance of Halo Link connected to a practice''s PMS database.

    - **Halo GUID:** A unique identifier for a site, used by Halo Connect to route queries.

    - **PMS:** Practice Management Software.

    - **PMS ID:** The identifier assigned to a site by the PMS vendor.

    '
servers:
- url: https://api.haloconnect.io
  description: Production
- url: https://api.stage.haloconnect.io
  description: Stage
security:
- SubscriptionKey: []
tags:
- name: Sites
  description: Endpoints for practice onboarding and site metadata.
paths:
  /integrator/pair-site:
    post:
      tags:
      - Sites
      summary: Pair with a site
      description: Pair with a site to enable API access. Best Practice sites require a pairing code generated by the practice. Pairing is still required for other PMS types, but no pairing code is needed.
      operationId: Integrator_PairSite
      parameters:
      - name: practiceManagementSiteId
        in: query
        description: The PMS ID of the site to pair with.
        required: true
        schema:
          type: string
          example: 12345
      - name: practiceManagementName
        in: query
        description: The name of the Practice Management Software used by the site.
        required: true
        schema:
          type: string
          enum:
          - Best Practice
          - Zedmed
          - D4w
          example: Best Practice
      - name: pairingCode
        in: query
        description: A pairing code generated by the practice. Required for Best Practice sites only.
        schema:
          type: string
          example: ABC123
      responses:
        '200':
          $ref: '#/components/responses/200IntegratorGetSite'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'
        '502':
          $ref: '#/components/responses/502Error'
  /integrator/pairSite:
    post:
      tags:
      - Sites
      summary: Pair with a site (deprecated)
      description: '**Deprecated:** Use `/integrator/pair-site` instead. Pair with a site to enable API access. Best Practice sites require a pairing code generated by the practice. Pairing is still required for other PMS types, but no pairing code is needed.'
      deprecated: true
      operationId: pairSite
      parameters:
      - name: practiceManagementSiteId
        in: query
        description: The PMS ID of the site to pair with.
        required: true
        schema:
          type: string
          example: 12345
      - name: practiceManagementName
        in: query
        description: The name of the Practice Management Software used by the site.
        required: true
        schema:
          type: string
          enum:
          - Best Practice
          - Zedmed
          - D4w
          example: Best Practice
      - name: pairingCode
        in: query
        description: A pairing code generated by the practice. Required for Best Practice sites only.
        schema:
          type: string
          example: ABC123
      responses:
        '200':
          $ref: '#/components/responses/200IntegratorGetSite'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'
        '502':
          $ref: '#/components/responses/502Error'
  /integrator/sites:
    get:
      tags:
      - Sites
      summary: Find sites by PMS ID
      description: Retrieve Halo GUIDs for sites matching the query parameters. Use this to exchange a known PMS ID for the corresponding Halo GUID.
      operationId: getSites
      parameters:
      - $ref: '#/components/parameters/PracticeManagementSiteIdRequired'
      - $ref: '#/components/parameters/PracticeManagementName'
      responses:
        '200':
          $ref: '#/components/responses/200IntegratorGetSites'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '500':
          $ref: '#/components/responses/500Error'
  /integrator/sites/{siteId}:
    get:
      tags:
      - Sites
      summary: Get site status
      description: Check the status of a site using its Halo GUID.
      operationId: getSite
      parameters:
      - $ref: '#/components/parameters/SiteId'
      responses:
        '200':
          $ref: '#/components/responses/200IntegratorGetSite'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'
components:
  responses:
    500Error:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              status: 500
              statusText: Internal Server Error
              message: Failed to create query container in CosmosDB.
    403Error:
      description: Access to resource is forbidden.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              status: 403
              statusText: Forbidden
              message: Access denied due to missing subscription key. Make sure to include subscription key when making requests to an API.
    200IntegratorGetSites:
      description: Sites retrieved.
      content:
        application/json:
          schema:
            type: object
            properties:
              sites:
                type: array
                items:
                  $ref: '#/components/schemas/SiteForIntegrator'
    404Error:
      description: The server cannot find the requested resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              status: 404
              statusText: Not Found
              message: The server cannot find the requested resource.
    400Error:
      description: Invalid request path parameter or body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              status: 400
              statusText: Bad Request
              message: Malformed SQL
    401Error:
      description: Unauthorized request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              status: 401
              statusText: Unauthorized
              message: Access denied due to missing subscription key. Make sure to include subscription key when making requests to an API.
    502Error:
      description: Bad gateway. The practice management software returned an unexpected error or result code.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              status: 502
              statusText: Bad Gateway
              message: The practice management software returned an unexpected result code.
    200IntegratorGetSite:
      description: Site retrieved.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SiteForIntegrator'
  schemas:
    SiteStatus:
      type: string
      description: Status of the site.
      enum:
      - initialising
      - active
      - removed
      - uninstalled
    SiteForIntegrator:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/SiteId'
        pmsType:
          $ref: '#/components/schemas/PMSType'
        availability:
          $ref: '#/components/schemas/SiteAvailability'
        status:
          $ref: '#/components/schemas/SiteStatus'
        haloLinkVersion:
          $ref: '#/components/schemas/HaloLinkVersion'
        enrichedAt:
          type: string
          format: date-time
          description: When the PracticeMetadata was last enriched from the Site, as a DateTime in UTC.
        catalogue:
          $ref: '#/components/schemas/SiteCatalogues'
        practiceMetadata:
          $ref: '#/components/schemas/PracticeMetadata'
        name:
          deprecated: true
          type: string
          description: Name of the site.
          example: Halo Clinic
        practiceManagementSiteId:
          deprecated: true
          type: string
          description: Id of the site as issued by the practice management software.
        practiceManagementName:
          deprecated: true
          type: string
          description: Name of the practice management software.
          enum:
          - Best Practice
          - Zedmed
          - D4w
        practiceManagementVersion:
          deprecated: true
          type: string
          description: Version of the practice management software when Halo Link was installed. Note this will not change when the practice management software is updated.
          example: 3.4.1
        createdAt:
          deprecated: true
          type: string
          format: date-time
        authoritative:
          deprecated: true
          type: boolean
          description: In the case there are multiple sites configured with the same Practice Management Software Site Id, only one of the sites is registered in Halo Connect as the authoritative site. This is the production site to which queries are normally routed. Non-authoritative sites may be used by practices as backups, for testing or temporarily during migrations.
          example: true
        clientTimestampUTC:
          deprecated: true
          type: string
          format: date-time
          description: Last updated time on a site. Date in UTC.
          example: '2022-12-25T12:25:01Z'
        heartbeatTimestampUTC:
          deprecated: true
          type: string
          format: date-time
          description: Last updated time on Halo Api server. Date in UTC.
          example: '2022-12-25T12:25:01Z'
    HaloLinkVersion:
      type: string
      format: version
      description: Assembly version of Halo Link client making the call. Usually CalVer [YY.MMDD.BuildNumber.0]
      example: 22.1207.209
    PracticeMetadata:
      type: object
      properties:
        pmsType:
          $ref: '#/components/schemas/PMSType'
        practiceName:
          type: string
          example: Halo Clinic South
          description: The name of the practice.
        practiceManagementSiteId:
          type: string
          format: string
          example: '12345'
          description: The siteId of the practice management software.
        practiceManagementVersion:
          type: string
          example: 3.4.1
          description: The version of the practice management software.
    PMSType:
      enum:
      - BestPractice
      - Zedmed
      - D4w
      example: BestPractice
      description: The name of the practice management software.
    SiteAvailability:
      type: string
      description: Availability of the site based on time last heard from the site.
      enum:
      - online
      - offline
      - unreachable
    PracticeManagementName:
      type: string
      description: Name of the practice management software.
      enum:
      - Best Practice
      - Zedmed
      - D4w
    SiteCatalogues:
      type: array
      description: List of catalogues (databases) available for the site.
      items:
        type: object
        properties:
          name:
            type: string
            example: Patients
            description: The name of the catalogue that can be queried.
          isDefault:
            type: boolean
            example: true
            description: If no catalogue is specified in the Query POST, the default catalogue will be used.
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            status:
              type: integer
              format: httpStatus
            statusText:
              type: string
              format: httpStatusPhrase
            message:
              type: string
    SiteId:
      type: string
      format: uuid
      description: Halo GUID of the site.
  parameters:
    PracticeManagementSiteIdRequired:
      name: practiceManagementSiteId
      in: query
      description: Filters by the PMS Site Id.
      schema:
        type: string
      required: true
    PracticeManagementName:
      name: practiceManagementName
      in: query
      description: Filters by the name of the Practice Management Software used by the site.
      schema:
        $ref: '#/components/schemas/PracticeManagementName'
      required: true
    SiteId:
      name: siteId
      in: path
      description: Halo GUID of the site.
      required: true
      schema:
        type: string
  securitySchemes:
    SubscriptionKey:
      type: apiKey
      name: Ocp-Apim-Subscription-Key
      in: header
      description: The subscription key for the API.