Halo Connect Logo
API docs by Redocly

Halo Cloud API for Integrators (26.128.8251)

Download OpenAPI specification:

Halo Connect Support: support@haloconnect.io License: Copyright © Halo Connect 2023

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 or blog.

Prerequisites

All API endpoints require an active pairing with the target site. Use the Pair with a site endpoint to establish access before making queries.

Definitions

For detailed documentation and guides, see our documentation portal.

  • 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.

Sites

Endpoints for practice onboarding and site metadata.

Pair with a site

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.

Authorizations:
SubscriptionKey
query Parameters
practiceManagementSiteId
required
string
Example: practiceManagementSiteId=12345

The PMS ID of the site to pair with.

practiceManagementName
required
string
Enum: "Best Practice" "Zedmed" "D4w"
Example: practiceManagementName=Best Practice

The name of the Practice Management Software used by the site.

pairingCode
string
Example: pairingCode=ABC123

A pairing code generated by the practice. Required for Best Practice sites only.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "pmsType": "BestPractice",
  • "availability": "online",
  • "status": "initialising",
  • "haloLinkVersion": "22.1207.209",
  • "enrichedAt": "2019-08-24T14:15:22Z",
  • "catalogue": [
    ],
  • "practiceMetadata": {
    },
  • "name": "Halo Clinic",
  • "practiceManagementSiteId": "string",
  • "practiceManagementName": "Best Practice",
  • "practiceManagementVersion": "3.4.1",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "authoritative": true,
  • "clientTimestampUTC": "2022-12-25T12:25:01Z",
  • "heartbeatTimestampUTC": "2022-12-25T12:25:01Z"
}

Pair with a site (deprecated) Deprecated

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.

Authorizations:
SubscriptionKey
query Parameters
practiceManagementSiteId
required
string
Example: practiceManagementSiteId=12345

The PMS ID of the site to pair with.

practiceManagementName
required
string
Enum: "Best Practice" "Zedmed" "D4w"
Example: practiceManagementName=Best Practice

The name of the Practice Management Software used by the site.

pairingCode
string
Example: pairingCode=ABC123

A pairing code generated by the practice. Required for Best Practice sites only.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "pmsType": "BestPractice",
  • "availability": "online",
  • "status": "initialising",
  • "haloLinkVersion": "22.1207.209",
  • "enrichedAt": "2019-08-24T14:15:22Z",
  • "catalogue": [
    ],
  • "practiceMetadata": {
    },
  • "name": "Halo Clinic",
  • "practiceManagementSiteId": "string",
  • "practiceManagementName": "Best Practice",
  • "practiceManagementVersion": "3.4.1",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "authoritative": true,
  • "clientTimestampUTC": "2022-12-25T12:25:01Z",
  • "heartbeatTimestampUTC": "2022-12-25T12:25:01Z"
}

Find sites by PMS ID

Retrieve Halo GUIDs for sites matching the query parameters. Use this to exchange a known PMS ID for the corresponding Halo GUID.

Authorizations:
SubscriptionKey
query Parameters
practiceManagementSiteId
required
string

Filters by the PMS Site Id.

practiceManagementName
required
string (PracticeManagementName)
Enum: "Best Practice" "Zedmed" "D4w"

Filters by the name of the Practice Management Software used by the site.

Responses

Response samples

Content type
application/json
{
  • "sites": [
    ]
}

Get site status

Check the status of a site using its Halo GUID.

Authorizations:
SubscriptionKey
path Parameters
siteId
required
string

Halo GUID of the site.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "pmsType": "BestPractice",
  • "availability": "online",
  • "status": "initialising",
  • "haloLinkVersion": "22.1207.209",
  • "enrichedAt": "2019-08-24T14:15:22Z",
  • "catalogue": [
    ],
  • "practiceMetadata": {
    },
  • "name": "Halo Clinic",
  • "practiceManagementSiteId": "string",
  • "practiceManagementName": "Best Practice",
  • "practiceManagementVersion": "3.4.1",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "authoritative": true,
  • "clientTimestampUTC": "2022-12-25T12:25:01Z",
  • "heartbeatTimestampUTC": "2022-12-25T12:25:01Z"
}

SQL Passthrough

Send SQL queries to practices as immediate, async or registered queries.

Immediate queries are small, time-sensitive queries that return a result in seconds. Response size is limited to 8MB.

Async queries are queued for execution and results can be retrieved later. The workflow is:

  1. Submit async query – Creates a query and returns a queryId on success.
  2. Get query status – Check query status. When complete, includes pagination details.
  3. Get query result page – Retrieve result pages using the pagination info from the status response.

Registered Queries are also supported. See the Registered Queries section for more information.

Execute immediate query

Send an immediate query to a site and receive the result in the response.

Query status can also be retrieved using the GET Query status endpoint.

Authorizations:
SubscriptionKey
path Parameters
siteId
required
string

Halo GUID of the site.

Request Body schema: application/json
maxTimeInQueue
number <milli-seconds> (ImmediateMaxTimeInQueue) [ 0 .. 60000 ]
required
object (Command)
catalogue
string (Catalogue)

Indicates which database to run against. If no catalogue is specified a default catalogue will be chosen instead. Supported for all PMS with multiple databases. Database catalogues, including the default catalogue, can be identified from the catalogue.name property returned by the Site API endpoints, and are consistent across all sites of a single PMS type.

Responses

Request samples

Content type
application/json
{
  • "maxTimeInQueue": 15000,
  • "command": {
    },
  • "catalogue": "Patients"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "integratorId": "1acd5efb-e960-4c96-8a84-ca37f187f58b",
  • "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
  • "mode": "immediate",
  • "maxTimeInQueue": 15000,
  • "commandSize": 98,
  • "requestSize": 98,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "status": "successful",
  • "statusTiming": {
    },
  • "metrics": {
    },
  • "result": {
    },
  • "resultSize": 98,
  • "completedAt": "2019-08-24T14:15:22Z"
}

Submit async query

Queue an async query for execution. Use the GET Query status endpoint to check progress and retrieve pagination details for results.

Authorizations:
SubscriptionKey
path Parameters
siteId
required
string

Halo GUID of the site.

Request Body schema: application/json
maxTimeInQueue
number <milli-seconds> (AsyncMaxTimeInQueue) [ 0 .. 7200000 ]
required
object (Command)
catalogue
string (Catalogue)

Indicates which database to run against. If no catalogue is specified a default catalogue will be chosen instead. Supported for all PMS with multiple databases. Database catalogues, including the default catalogue, can be identified from the catalogue.name property returned by the Site API endpoints, and are consistent across all sites of a single PMS type.

Responses

Request samples

Content type
application/json
{
  • "maxTimeInQueue": 900000,
  • "command": {
    },
  • "catalogue": "Patients"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "integratorId": "1acd5efb-e960-4c96-8a84-ca37f187f58b",
  • "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
  • "mode": "async",
  • "status": "initialising",
  • "maxTimeInQueue": 900000,
  • "commandSize": 98,
  • "requestSize": 98,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "statusTiming": {
    }
}

Get query status

Check the status of an immediate or async query.

For async queries, successful responses include a results object with pagination details for retrieving result pages. Immediate queries do not include pagination since results are returned with the initial request.

Authorizations:
SubscriptionKey
path Parameters
siteId
required
string

Halo GUID of the site.

queryId
required
string

Id of the query.

Responses

Response samples

Content type
application/json
Example
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "integratorId": "1acd5efb-e960-4c96-8a84-ca37f187f58b",
  • "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
  • "mode": "async",
  • "status": "successful",
  • "maxTimeInQueue": 900000,
  • "commandSize": 98,
  • "requestSize": 98,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "statusTiming": {
    },
  • "metrics": {
    },
  • "result": {
    },
  • "resultSize": 98,
  • "completedAt": "2019-08-24T14:15:22Z"
}

Get batch query status

Returns the status of the specified queries for a site. Submit an array of query IDs in the request body to retrieve their current status.

Each result indicates whether the query was found or not found, and includes the full query details when found.

Authorizations:
SubscriptionKey
path Parameters
siteId
required
string

Halo GUID of the site.

Request Body schema: application/json
queryIds
required
Array of strings <uuid> [ items <uuid > ]

Array of query IDs to retrieve status for.

Responses

Request samples

Content type
application/json
{
  • "queryIds": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Get query result page

Get a result page from a successful async query.

Authorizations:
SubscriptionKey
path Parameters
siteId
required
string

Halo GUID of the site.

queryId
required
string

Id of the query.

pageNumber
required
number >= 1

Page number of the results for a query.

Responses

Response samples

Content type
application/json
Example
{
  • "data": "e2lk...",
  • "parameters": [
    ]
}

Stream result page

Streams the JSON content of a single page of query results. This is useful for large result sets that are paginated and delivered as streamed responses to reduce memory usage.

Authorizations:
SubscriptionKey
path Parameters
siteId
required
string

Halo GUID of the site.

queryId
required
string

Id of the query.

pageNumber
required
number >= 1

Page number of the results for a query.

Responses

Response samples

Content type
application/json
"string"

FHIR

Query practices using FHIR resources.

Search FHIR resources

Send a FHIR query to a site and receive the result in the response.

Include the resource name and search parameters in fhirParameters. Example: Patient?given=John

See the FHIR API docs for supported resources and parameters.

Authorizations:
SubscriptionKey
path Parameters
siteId
required
string

Halo GUID of the site.

fhirParameters
required
string

Resource names and search parameters per the R4 FHIR specification for using RESTful APIs and search.

Responses

Response samples

Content type
application/json
Example
{
  • "application/json": {
    }
}

Search FHIR resources (POST)

Send a FHIR search query with parameters in the request body.

POST is recommended for sensitive queries containing personally identifiable information (PII), as it avoids URL length limits and keeps parameters out of logs.

See the FHIR API docs for supported resources and parameters. Errors may return as HTTP errors or FHIR OperationOutcome resources.

Authorizations:
SubscriptionKey
path Parameters
siteId
required
string

Halo GUID of the site.

resource
required
string

The name of the FHIR resource to search for.

Request Body schema: application/x-www-form-urlencoded
required

FHIR search parameters.

property name*
additional property
any

Responses

Request samples

Content type
application/x-www-form-urlencoded
given=John&birthdate=gt1900-01-01&_sort=birthdate

Response samples

Content type
application/json
{
  • "application/json": {
    }
}

Registered Queries

Recurring queries that run at a specified frequency, and can be used to monitor for updates or new records. This type is recommended for polling use cases.

Create registered query

Create a registered query to be queued for execution.

Authorizations:
SubscriptionKey
path Parameters
siteId
required
string

Halo GUID of the site.

Request Body schema: application/json
name
required
string

Customer set identifier for this registered query.

registeredQueryType
required
string
Value: "query"
frequency
required
number

Seconds between each query execution.

duration
required
number

Duration in seconds the query will run for. Up to 86400 seconds (24 hours).

required
object

Command to be executed by the registered query.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "registeredQueryType": "query",
  • "frequency": 300,
  • "duration": 43200,
  • "registerCommand": {
    }
}

Response samples

Content type
application/json
{
  • "id": "785f1ae1-1234-abcd-56ef-8679258f4aee"
}

List registered queries

List all registered queries that are currently active and queued for execution.

Authorizations:
SubscriptionKey
path Parameters
siteId
required
string

Halo GUID of the site.

Responses

Response samples

Content type
application/json
{
  • "registeredQueries": [
    ]
}

Get registered query details

Get the details of a registered query.

Authorizations:
SubscriptionKey
path Parameters
siteId
required
string

Halo GUID of the site.

queryId
required
string

Id of the query.

Responses

Response samples

Content type
application/json
Example
{
  • "id": "d8d667d9-1234-abcd-56ef-1234567890ab",
  • "name": "Test",
  • "registeredQueryType": "query",
  • "status": "enabled",
  • "frequency": 60,
  • "duration": 120,
  • "createdAt": "2025-05-27T05:23:40.983Z",
  • "lastHash": "dOFA...",
  • "metrics": {
    }
}

Cancel registered query

Cancel a registered query that is currently queued for execution.

Authorizations:
SubscriptionKey
path Parameters
siteId
required
string

Halo GUID of the site.

queryId
required
string

Id of the query.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get registered query results

Get the result of a registered query that has completed execution.

Authorizations:
SubscriptionKey
path Parameters
siteId
required
string

Halo GUID of the site.

queryId
required
string

Id of the query.

Responses

Response samples

Content type
application/json
{
  • "data": "e2lk...",
  • "parameters": [
    ],
  • "rows": 12,
  • "size": 25
}