Halo Cloud API for Integrators (24.708.3114)

Download OpenAPI specification:Download

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

200
400
401
403
500

Content type

application/json

{"sites": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pmsType": "BestPractice",
"availability": "online",
"status": "initialising",
"haloLinkVersion": "22.1207.209",
"enrichedAt": "2019-08-24T14:15:22Z",
"catalogue": [{"name": "Patients",
"isDefault": true
}
],
"practiceMetadata": {"pmsType": "BestPractice",
"practiceName": "Halo Clinic South",
"practiceManagementSiteId": "12345",
"practiceManagementVersion": "3.4.1"
},
"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"
}
]
}

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": [{"name": "Patients",
"isDefault": true
}
],
"practiceMetadata": {"pmsType": "BestPractice",
"practiceName": "Halo Clinic South",
"practiceManagementSiteId": "12345",
"practiceManagementVersion": "3.4.1"
},
"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:

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

Payload

Content type

application/json

{"maxTimeInQueue": 15000,
"command": {"text": "GetPatientID",
"executionMode": "reader",
"type": "text",
"parameters": [{"name": "@siteid",
"direction": "output",
"type": "BigInt",
"value": "66",
"size": 43
}
]
},
"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,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"status": "successful",
"statusTiming": {"initialising": {"startTime": "2019-08-24T14:15:22Z",
"endTime": "2019-08-24T14:15:22Z"
},
"executing": {"startTime": "2019-08-24T14:15:22Z",
"endTime": "2019-08-24T14:15:22Z"
}
},
"metrics": {"sqlExecutionDuration": 1000
},
"result": {"rows": 30,
"size": 25,
"data": "e2lkIjogNDIsaW5mbyI6IHsgIm5hbWUiOiAiSmFuZSIsICJzdXJuYW1lIjogIlNtaXRoIiB9LGRvYiI6ICIzMDIyLTExLTA0VDEyOjAwOjAwfQ==",
"parameters": [{"name": "@siteid",
"direction": "output",
"type": "BigInt",
"value": "66",
"size": 43
}
]
}
}

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

Payload

Content type

application/json

{"maxTimeInQueue": 900000,
"command": {"text": "GetPatientID",
"executionMode": "reader",
"type": "text",
"parameters": [{"name": "@siteid",
"direction": "output",
"type": "BigInt",
"value": "66",
"size": 43
}
]
},
"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,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"statusTiming": {"initialising": {"startTime": "2019-08-24T14:15:22Z"
}
}
}

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

successful

{"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,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"statusTiming": {"initialising": {"startTime": "2019-08-24T14:15:22Z",
"endTime": "2019-08-24T14:15:22Z"
},
"queued": {"startTime": "2019-08-24T14:15:22Z",
"endTime": "2019-08-24T14:15:22Z"
},
"executing": {"startTime": "2019-08-24T14:15:22Z",
"endTime": "2019-08-24T14:15:22Z"
},
"uploading": {"startTime": "2019-08-24T14:15:22Z"
}
},
"metrics": {"sqlExecutionDuration": 1000
},
"result": {"rows": 30,
"size": 25,
"pages": [{"pageNumber": 1,
"status": "queued",
"size": 0,
"rows": {"count": 10,
"rangeStart": 1,
"rangeEnd": 11
}
}
]
}
}

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

Query Result

{"data": "e2lkIjogNDIsaW5mbyI6IHsgIm5hbWUiOiAiSmFuZSIsICJzdXJuYW1lIjogIlNtaXRoIiB9LGRvYiI6ICIzMDIyLTExLTA0VDEyOjAwOjAwfQ==",
"parameters": [{"name": "@siteid",
"direction": "output",
"type": "BigInt",
"value": "66",
"size": 43
}
]
}

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

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.

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

Payload

Content type

application/x-www-form-urlencoded

given:exact=John&birthdate=gt1900-01-01&_sort=birthdate