find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/halo-connect-sites-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no email required.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

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':
          description: Site retrieved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: Halo GUID of the site.
                  pmsType:
                    enum:
                    - BestPractice
                    - Zedmed
                    - D4w
                    example: BestPractice
                    description: The name of the practice management software.
                  availability:
                    type: string
                    description: Availability of the site based on time last heard from the site.
                    enum:
                    - online
                    - offline
                    - unreachable
                  status:
                    type: string
                    description: Status of the site.
                    enum:
                    - initialising
                    - active
                    - removed
                    - uninstalled
                  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
                  enrichedAt:
                    type: string
                    format: date-time
                    description: When the PracticeMetadata was last enriched from the Site, as a DateTime in UTC.
                  catalogue:
                    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.
                  practiceMetadata:
                    type: object
                    properties:
                      pmsType:
                        enum:
                        - BestPractice
                        - Zedmed
                        - D4w
                        example: BestPractice
                        description: The name of the practice management software.
                      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.
                  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'
        '400':
          description: Invalid request path parameter or body.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      status:
                        type: integer
                        format: httpStatus
                      statusText:
                        type: string
                        format: httpStatusPhrase
                      message:
                        type: string
              example:
                error:
                  status: 400
                  statusText: Bad Request
                  message: Malformed SQL
        '401':
          description: Unauthorized request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      status:
                        type: integer
                        format: httpStatus
                      statusText:
                        type: string
                        format: httpStatusPhrase
                      message:
                        type: string
              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.
        '403':
          description: Access to resource is forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      status:
                        type: integer
                        format: httpStatus
                      statusText:
                        type: string
                        format: httpStatusPhrase
                      message:
                        type: string
              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.
        '404':
          description: The server cannot find the requested resource.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      status:
                        type: integer
                        format: httpStatus
                      statusText:
                        type: string
                        format: httpStatusPhrase
                      message:
                        type: string
              example:
                error:
                  status: 404
                  statusText: Not Found
                  message: The server cannot find the requested resource.
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      status:
                        type: integer
                        format: httpStatus
                      statusText:
                        type: string
                        format: httpStatusPhrase
                      message:
                        type: string
              example:
                error:
                  status: 500
                  statusText: Internal Server Error
                  message: Failed to create query container in CosmosDB.
        '502':
          description: Bad gateway. The practice management software returned an unexpected error or result code.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      status:
                        type: integer
                        format: httpStatus
                      statusText:
                        type: string
                        format: httpStatusPhrase
                      message:
                        type: string
              example:
                error:
                  status: 502
                  statusText: Bad Gateway
                  message: The practice management software returned an unexpected result code.
  /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':
          description: Site retrieved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: Halo GUID of the site.
                  pmsType:
                    enum:
                    - BestPractice
                    - Zedmed
                    - D4w
                    example: BestPractice
                    description: The name of the practice management software.
                  availability:
                    type: string
                    description: Availability of the site based on time last heard from the site.
                    enum:
                    - online
                    - offline
                    - unreachable
                  status:
                    type: string
                    description: Status of the site.
                    enum:
                    - initialising
                    - active
                    - removed
                    - uninstalled
                  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
                  enrichedAt:
                    type: string
                    format: date-time
                    description: When the PracticeMetadata was last enriched from the Site, as a DateTime in UTC.
                  catalogue:
                    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.
                  practiceMetadata:
                    type: object
                    properties:
                      pmsType:
                        enum:
                        - BestPractice
                        - Zedmed
                        - D4w
                        example: BestPractice
                        description: The name of the practice management software.
                      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.
                  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'
        '400':
          description: Invalid request path parameter or body.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      status:
                        type: integer
                        format: httpStatus
                      statusText:
                        type: string
                        format: httpStatusPhrase
                      message:
                        type: string
              example:
                error:
                  status: 400
                  statusText: Bad Request
                  message: Malformed SQL
        '401':
          description: Unauthorized request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      status:
                        type: integer
                        format: httpStatus
                      statusText:
                        type: string
                        format: httpStatusPhrase
                      message:
                        type: string
              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.
        '403':
          description: Access to resource is forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      status:
                        type: integer
                        format: httpStatus
                      statusText:
                        type: string
                        format: httpStatusPhrase
                      message:
                        type: string
              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.
        '404':
          description: The server cannot find the requested resource.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      status:
                        type: integer
                        format: httpStatus
                      statusText:
                        type: string
                        format: httpStatusPhrase
                      message:
                        type: string
              example:
                error:
                  status: 404
                  statusText: Not Found
                  message: The server cannot find the requested resource.
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      status:
                        type: integer
                        format: httpStatus
                      statusText:
                        type: string
                        format: httpStatusPhrase
                      message:
                        type: string
              example:
                error:
                  status: 500
                  statusText: Internal Server Error
                  message: Failed to create query container in CosmosDB.
        '502':
          description: Bad gateway. The practice management software returned an unexpected error or result code.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      status:
                        type: integer
                        format: httpStatus
                      statusText:
                        type: string
                        format: httpStatusPhrase
                      message:
                        type: string
              example:
                error:
                  status: 502
                  statusText: Bad Gateway
                  message: The practice management software returned an unexpected result code.
  /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:
      - name: practiceManagementSiteId
        in: query
        description: Filters by the PMS Site Id.
        schema:
          type: string
        required: true
      - name: practiceManagementName
        in: query
        description: Filters by the name of the Practice Management Software used by the site.
        schema:
          type: string
          description: Name of the practice management software.
          enum:
          - Best Practice
          - Zedmed
          - D4w
        required: true
      responses:
        '200':
          description: Sites retrieved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  sites:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                          description: Halo GUID of the site.
                        pmsType:
                          enum:
                          - BestPractice
                          - Zedmed
                          - D4w
                          example: BestPractice
                          description: The name of the practice management software.
                        availability:
                          type: string
                          description: Availability of the site based on time last heard from the site.
                          enum:
                          - online
                          - offline
                          - unreachable
                        status:
                          type: string
                          description: Status of the site.
                          enum:
                          - initialising
                          - active
                          - removed
                          - uninstalled
                        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
                        enrichedAt:
                          type: string
                          format: date-time
                          description: When the PracticeMetadata was last enriched from the Site, as a DateTime in UTC.
                        catalogue:
                          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.
                        practiceMetadata:
                          type: object
                          properties:
                            pmsType:
                              enum:
                              - BestPractice
                              - Zedmed
                              - D4w
                              example: BestPractice
                              description: The name of the practice management software.
                            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.
                        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'
        '400':
          description: Invalid request path parameter or body.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      status:
                        type: integer
                        format: httpStatus
                   

# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/halo-connect/refs/heads/main/openapi/halo-connect-sites-api-openapi.yml