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 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. '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. /integrator/sites/{siteId}: get: tags: - Sites summary: Get site status description: Check the status of a site using its Halo GUID. operationId: getSite parameters: - name: siteId in: path description: Halo GUID of the site. required: true schema: type: string 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. components: securitySchemes: SubscriptionKey: type: apiKey name: Ocp-Apim-Subscription-Key in: header description: The subscription key for the API.