Halo Cloud API for Desktop Applications (26.128.8251)

Download OpenAPI specification:

Introduction

This API reference documents the endpoints available for desktop application integration with the Halo Connect Cloud API. It covers:

Tokens – Obtain authorization tokens for desktop applications
SQL Passthrough – Execute SQL queries against site 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.

Tokens

Obtain authorization tokens for desktop applications to authenticate API requests.

Get authorization token

This endpoint enables integrators to obtain an authorization token for a specific desktop application associated with a given Halo GUID. The token is required to authenticate subsequent requests to the SQL Passthrough or FHIR for that desktop application.

Authorizations:

SubscriptionKey

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

grant_type required	string Value: "urn:halo-connect:oauth:desktop-token" Must be set to urn:halo-connect:oauth:desktop-token
device_id required	string The unique identifier of the device
site_id required	string The Halo GUID of the site

Responses

Request samples

Payload

Content type

application/x-www-form-urlencoded

grant_type=urn%3Ahalo-connect%3Aoauth%3Adesktop-token&device_id=example-device-123&site_id=example-site-guid

Response samples

200

Content type

application/json

{"access_token": "string",
"token_type": "string",
"expires_in": 0
}

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:

Submit async query – Creates a query and returns a queryId on success.
Get query status – Check query status. When complete, includes pagination details.
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:

(AuthorizationHeaderDeviceIdHeader)

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

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,
"commandSize": 98,
"requestSize": 98,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"status": "successful",
"statusTiming": {"initialising": {"startTime": "2019-08-24T14:15:22Z"
},
"executing": {"startTime": "2019-08-24T14:15:22Z"
},
"downloading": {"startTime": "2019-08-24T14:15:22Z"
},
"uploading": {"startTime": "2019-08-24T14:15:22Z"
}
},
"metrics": {"sqlExecutionDuration": 1000
},
"result": {"rows": 30,
"size": 25,
"data": "e2lk...",
"parameters": [{"name": "@siteid",
"direction": "output",
"type": "BigInt",
"value": "66",
"size": 43
}
]
},
"resultSize": 98,
"completedAt": "2019-08-24T14:15:22Z"
}

Submit async query

Queue an async query for execution at the specified site.

Authorizations:

(AuthorizationHeaderDeviceIdHeader)

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

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,
"commandSize": 98,
"requestSize": 98,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"statusTiming": {"initialising": {"startTime": "2019-08-24T14:15:22.847Z"
}
}
}

Get query status

Check the status of an immediate or async query.

For completed async queries, the response includes 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:

(AuthorizationHeaderDeviceIdHeader)

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

Get query result page

Get a result page from a successful async query.

Authorizations:

(AuthorizationHeaderDeviceIdHeader)

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": "e2lk...",
"parameters": [{"name": "@siteid",
"direction": "output",
"type": "BigInt",
"value": "66",
"size": 43
}
]
}

FHIR

Query practice data 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 docs for supported resources and parameters.

Authorizations:

(AuthorizationHeaderDeviceIdHeader)

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

FhirResource

{"application/json": {"resourceType": "Patient",
"id": "1",
"name": [{"use": "official",
"text": "Mr John Smith",
"family": "Smith",
"given": ["John"
],
"prefix": ["Mr"
]
}
]
}
}

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 docs for supported resources and parameters. Errors may return as HTTP errors or FHIR OperationOutcome resources.

Authorizations:

(AuthorizationHeaderDeviceIdHeader)

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

Payload

Content type

application/x-www-form-urlencoded

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

Response samples

Content type

application/json

{"application/json": {"resourceType": "Bundle",
"type": "searchset",
"total": 0
}
}

Registered Queries

Create registered query

Create a registered query to be queued for execution.

Authorizations:

(AuthorizationHeaderDeviceIdHeader)

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

Payload

Content type

application/json

{"name": "string",
"registeredQueryType": "query",
"frequency": 300,
"duration": 43200,
"registerCommand": {"command": {"text": "GetPatientID",
"executionMode": "reader",
"type": "text",
"parameters": [{"name": "@siteid",
"direction": "output",
"type": "BigInt",
"value": "66",
"size": 43
}
]
}
}
}

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:

(AuthorizationHeaderDeviceIdHeader)

path Parameters

siteId

required

string

Halo GUID of the site.

Responses

Response samples

Content type

application/json

{"registeredQueries": [{"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": {"lastExecutionDuration": 15,
"executionSucceededCount": 1,
"executionFailedCount": 0,
"resultSizeSum": 8,
"requestSize": 180,
"lastSucceededAt": "2025-05-27T05:23:46.836Z"
}
},
{"id": "6cf4e9be-1234-abcd-56ef-1234567890ab",
"name": "Test",
"registeredQueryType": "query",
"status": "completed",
"frequency": 60,
"duration": 120,
"createdAt": "2025-05-27T04:57:48.791Z",
"completedAt": "2025-05-27T04:59:54.226Z",
"lastErrorDetails": {"errorType": "mssql",
"errorCode": 2812,
"errorMessage": "Could not find stored procedure 'selct'."
},
"metrics": {"lastExecutionDuration": 0,
"executionSucceededCount": 0,
"executionFailedCount": 3,
"resultSizeSum": 0,
"requestSize": 179,
"lastFailedAt": "2025-05-27T04:59:54.226Z"
}
}
]
}

Get registered query details

Get the details of a registered query.

Authorizations:

(AuthorizationHeaderDeviceIdHeader)

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 ongoing query

{"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": {"lastExecutionDuration": 15,
"executionSucceededCount": 1,
"executionFailedCount": 0,
"resultSizeSum": 8,
"requestSize": 180,
"lastSucceededAt": "2025-05-27T05:23:46.836Z"
}
}

Cancel registered query

Cancel a registered query that is currently queued for execution.

Authorizations:

(AuthorizationHeaderDeviceIdHeader)

path Parameters

siteId required	string Halo GUID of the site.
queryId required	string Id of the query.

Responses

Response samples

400
401
403
404
500

Content type

application/json

{"error": {"status": 400,
"statusText": "Bad Request",
"message": "Malformed SQL"
}
}

Get registered query results

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

Authorizations:

(AuthorizationHeaderDeviceIdHeader)

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": [{"name": "@siteid",
"direction": "output",
"type": "BigInt",
"value": "66",
"size": 43
}
],
"rows": 12,
"size": 25
}

Halo Cloud API for Desktop Applications (26.128.8251)

Introduction

Prerequisites

Definitions

Tokens

Get authorization token

Authorizations:

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

Responses

Request samples

Response samples

SQL Passthrough

Execute immediate query

Authorizations:

path Parameters

Request Body schema: application/json

Responses

Request samples

Response samples

Submit async query

Authorizations:

path Parameters

Request Body schema: application/json

Responses

Request samples

Response samples

Get query status

Authorizations:

path Parameters

Responses

Response samples

Get query result page

Authorizations:

path Parameters

Responses

Response samples

FHIR

Search FHIR resources

Authorizations:

path Parameters

Responses

Response samples

Search FHIR resources (POST)

Authorizations:

path Parameters

Request Body schema: application/x-www-form-urlencodedrequired

Responses

Request samples

Response samples

Registered Queries

Create registered query

Authorizations:

path Parameters

Request Body schema: application/json

Responses

Request samples

Response samples

List registered queries

Authorizations:

path Parameters

Responses

Response samples

Get registered query details

Authorizations:

path Parameters

Responses

Response samples

Cancel registered query

Authorizations:

path Parameters

Responses

Response samples

Get registered query results

Authorizations:

path Parameters

Responses

Response samples

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