Halo Connect Logo
API docs by Redocly

Halo Cloud API for Integrators (24.823.3464)

Download OpenAPI specification:Download

E-mail: support@haloconnect.io License: Copyright © Halo Connect 2023

Introduction

This document outlines the API endpoints available to integrators using Halo Connect's Cloud APIs. It includes endpoints for the SQL Passthrough and FHIR API products, plus meta endpoints for fetching information about sites.

This API reference is defined using the OpenAPI Specification.

You can find out more about Halo Connect on our website and blog.

Definitions

For in-depth documentation and guides, see our main docs. The following is only a quick reference guide.

  • Site: An instance of Halo Link that is connected to a practice's PMS database.
  • Halo GUID: The unique identifier for a site which is used by Halo Connect to route queries.
  • PMS: Practice Management Software
  • PMS ID: The identifier for a site given to them by their PMS.
  • Authoritative server: A site which integrators are allowed to query.
  • Non-authoritative server: A site which integrators are not allowed to query, such as for a backup system.

Site APIs

Retrieve a site's Halo GUID or check its status.

Get Halo GUIDs

Retrieve the list of Halo GUIDs for Halo Connect sites that match all of the supplied query parameters. This endpoint allows integrators to exchange a known PMS ID (e.g. Best Practice Site ID) for the corresponding Halo GUID which can then be used to query the site.

Authorizations:
ApiKeyHeaderApiKeyQuery
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:
ApiKeyHeaderApiKeyQuery
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 API

Send SQL queries to practices as either immediate or async queries.

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

Async queries get queued for execution, and integrators can retrieve the results later. Async queries have three endpoints:

  1. Use the POST Send async query endpoint to create an async query. If the query is successfully queued, you will receive a 201 Async query created response which includes a queryID. You will need to note this queryID for checking the status of and retrieving the result of this query.
  2. Use the GET Get query status endpoint to check the status of the query. Once the query is complete and the status is successful, the response object will include a result field which gives details of the rows, size, and pages of the query result.
  3. Use the GET Get async result page endpoint to retrieve query result pages once the query is complete, using the page information returned by the GET Query status endpoint.

Send immediate query

This resource allows you to send an immediate query to a site, and receive a result or error in the POST response. The site to be queried is specified by its Halo GUID.

You can also get the status of an immediate query using the GET Query status endpoint listed under Async queries.

Authorizations:
ApiKeyHeaderApiKeyQuery
path Parameters
siteId
required
string

Halo GUID of the site.

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

Indicates which database to run against. If no catalogue is specified a default catalogue will be chosen instead. Currently only supported for Zedmed, if querying other PMS select the database in the query itself. Database catalogues can be identified from a site's database.name property 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,
  • "sqlQuerySize": 46,
  • "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"
}

Send async query

This resource allows you to send an async query to a site to be queued for execution. The site to be queried is specified by its Halo GUID.

Authorizations:
ApiKeyHeaderApiKeyQuery
path Parameters
siteId
required
string

Halo GUID of the site.

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

Indicates which database to run against. If no catalogue is specified a default catalogue will be chosen instead. Currently only supported for Zedmed, if querying other PMS select the database in the query itself. Database catalogues can be identified from a site's database.name property 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,
  • "sqlQuerySize": 46,
  • "commandSize": 98,
  • "requestSize": 98,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "statusTiming": {
    }
}

Get query status

Check the status of a query.

The same endpoint is used for both immediate and async queries, though it returns a different response with successful async queries returning a "results" object which includes pagination details for GET Result Page.

Also be aware immediate queries retrieved using this endpoint will not include a results object indicating pages since it is returned with the initial request unlike async queries.

Authorizations:
ApiKeyHeaderApiKeyQuery
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,
  • "sqlQuerySize": 46,
  • "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 result page

Get a result page from a successful async query.

Authorizations:
ApiKeyHeaderApiKeyQuery
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": "e2lkIjogNDIsaW5mbyI6IHsgIm5hbWUiOiAiSmFuZSIsICJzdXJuYW1lIjogIlNtaXRoIiB9LGRvYiI6ICIzMDIyLTExLTA0VDEyOjAwOjAwfQ==",
  • "parameters": [
    ]
}

FHIR API

Send FHIR queries to practices.

Get FHIR resources

This endpoint allows you to send a FHIR query to a site, and receive a result or error in the REST response. The site to be queried is specified by its Halo GUID.

See the FHIR API docs for more information about how to use the FHIR API and what it supports.

Resource names and search parameters should be included as fhirParameters. For example: sites/{siteId}/fhir/R4/Patient?given=John

Authorizations:
ApiKeyHeaderApiKeyQuery
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": {
    }
}

Post FHIR search

This resource allows you to send a FHIR query to a site, and receive a result or error in the REST response. The site to be queried is specified by its Halo GUID.

See the FHIR API docs for more information about how to use the FHIR API and what it supports.

Search parameters should be included in the body of the request. Using POST is recommended for sensitive and complex queries, particularly those that include PII. Putting the parameters in the request body increases security and reliability, and the length limitations of a GET request URL do not apply.

Errors may be a HTTP error or a FHIR OperationOutcome, depending on whether the error occurred in the FHIR engine or elsewhere.

Authorizations:
ApiKeyHeaderApiKeyQuery
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

FHIR search parameters.

property name*
additional property
any

Responses

Request samples

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

Response samples

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

Registered queries

List active registered queries

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

Authorizations:
ApiKeyHeaderApiKeyQuery
path Parameters
siteId
required
string

Halo GUID of the site.

Responses

Response samples

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

Create registered query

Create a registered query to be queued for execution.

Authorizations:
ApiKeyHeaderApiKeyQuery
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": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "status": "initialisationFailedCacheError",
  • "frequency": 300,
  • "duration": 43200,
  • "lastHash": "string",
  • "errorDetails": {
    },
  • "metrics": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "completedAt": "2019-08-24T14:15:22Z"
}

Get registered query

Get the details of a registered query.

Authorizations:
ApiKeyHeaderApiKeyQuery
path Parameters
siteId
required
string

Halo GUID of the site.

queryId
required
string

Id of the query.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "status": "initialisationFailedCacheError",
  • "frequency": 300,
  • "duration": 43200,
  • "lastHash": "string",
  • "errorDetails": {
    },
  • "metrics": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "completedAt": "2019-08-24T14:15:22Z"
}

Cancel registered query

Cancel a registered query that is currently queued for execution.

Authorizations:
ApiKeyHeaderApiKeyQuery
path Parameters
siteId
required
string

Halo GUID of the site.

queryId
required
string

Id of the query.

Responses

Response samples

Content type
application/json
{
  • "status": 400,
  • "statusText": "Bad Request",
  • "message": "Malformed SQL"
}

Get registered query result

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

Authorizations:
ApiKeyHeaderApiKeyQuery
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": "e2lkIjogNDIsaW5mbyI6IHsgIm5hbWUiOiAiSmFuZSIsICJzdXJuYW1lIjogIlNtaXRoIiB9LGRvYiI6ICIzMDIyLTExLTA0VDEyOjAwOjAwfQ==",
  • "parameters": [
    ],
  • "rows": 12,
  • "size": 25
}