Halo Connect Logo
API docs by Redocly

Halo Cloud API for Devices (25.528.5462)

Download OpenAPI specification:

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

Introduction

This document outlines the API endpoints available in Halo Connect’s Cloud APIs to enable Direct Device Integration. Integrator Token API: Handles authentication for secure API access. SQL Passthrough API: Allows devices to interact with site-specific databases. FHIR API: Facilitates seamless integration with healthcare data using FHIR standards.

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.

Integrator Token API

Provides an endpoint for integrators to obtain a token. This token is used to authenticate subsequent SQL Passthrough API calls or Fhir API calls for a specific device and Halo GUID.

Retrieve device authorization token

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

Authorizations:
ApiKeyHeader
Request Body schema: application/x-www-form-urlencoded
grant_type
required
string
Value: "urn:halo-connect:oauth:device-token"

Must be set to 'urn:halo-connect:oauth:device-token'

device_id
required
string

The unique identifier of the device

site_id
required
string

The Halo GUID of the site

Responses

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "string",
  • "expires_in": 0
}

SQL Passthrough API

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

Registered queries are also supported in the SQL Passthrough API. See the Registered queries section for more information.

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:
(AuthorizationHeaderDeviceIdHeader)
path Parameters
siteId
required
string

Halo GUID of the site.

Request Body schema: application/json
required
object (Command)
text
required
string

The SQL statement to execute or the name of the stored procedure to run.

executionMode
string (ExecutionMode)
Enum: "reader" "nonQuery" "scalar"

Selects between fetching data or writing to the database. reader executes the command (e.g. SELECT) and returns rows of data. nonQuery executes the command (e.g. UPDATE, INSERT, or DELETE) and does not return data. scalar returns first value of first row of query results. For Querys using RETURN @values please use returnValue Parameters.

type
string (CommandType)
Enum: "text" "storedProcedure"

Indicates how the text property is to be interpreted. text executes the SQL contained within the text property. storedProcedure calls the stored procedure named in the text property. storedProcedure is currently experimental.

Array of objects (Parameter)

Parameters are used to supply data to, or read outputs from, a stored procedure.

Array
name
string

The name of the parameter.

direction
string (Direction)
Enum: "output" "input" "inputOutput" "returnValue"

A value that indicates whether the parameter is input-only, output-only, bidirectional, or a stored procedure return value parameter.

type
string (Type)
Enum: "BigInt" "Binary" "Bit" "Char" "String" "Date" "DateTime" "DateTime2" "DateTimeOffset" "Decimal" "Float" "Image" "Int" "Money" "NChar" "NText" "NVarChar" "Real" "SmallDateTime" "SmallInt" "SmallMoney" "Structured" "Text" "Time" "Timestamp" "TinyInt" "Udt" "UniqueIdentifier" "VarBinary" "VarChar" "Variant" "Xml"

Specifies SQL Server-specific data type of a field, property.

value
string or null <base64 (output)> (Value)

Gets or sets the value of the parameter.

size
number (Size)

The maximum size, in bytes, of the data within the column.

maxTimeInQueue
number <milli-seconds> (ImmediateMaxTimeInQueue) [ 0 .. 60000 ]
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": {
    • "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,
  • "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"
}

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:
(AuthorizationHeaderDeviceIdHeader)
path Parameters
siteId
required
string

Halo GUID of the site.

Request Body schema: application/json
required
object (Command)
text
required
string

The SQL statement to execute or the name of the stored procedure to run.

executionMode
string (ExecutionMode)
Enum: "reader" "nonQuery" "scalar"

Selects between fetching data or writing to the database. reader executes the command (e.g. SELECT) and returns rows of data. nonQuery executes the command (e.g. UPDATE, INSERT, or DELETE) and does not return data. scalar returns first value of first row of query results. For Querys using RETURN @values please use returnValue Parameters.

type
string (CommandType)
Enum: "text" "storedProcedure"

Indicates how the text property is to be interpreted. text executes the SQL contained within the text property. storedProcedure calls the stored procedure named in the text property. storedProcedure is currently experimental.

Array of objects (Parameter)

Parameters are used to supply data to, or read outputs from, a stored procedure.

Array
name
string

The name of the parameter.

direction
string (Direction)
Enum: "output" "input" "inputOutput" "returnValue"

A value that indicates whether the parameter is input-only, output-only, bidirectional, or a stored procedure return value parameter.

type
string (Type)
Enum: "BigInt" "Binary" "Bit" "Char" "String" "Date" "DateTime" "DateTime2" "DateTimeOffset" "Decimal" "Float" "Image" "Int" "Money" "NChar" "NText" "NVarChar" "Real" "SmallDateTime" "SmallInt" "SmallMoney" "Structured" "Text" "Time" "Timestamp" "TinyInt" "Udt" "UniqueIdentifier" "VarBinary" "VarChar" "Variant" "Xml"

Specifies SQL Server-specific data type of a field, property.

value
string or null <base64 (output)> (Value)

Gets or sets the value of the parameter.

size
number (Size)

The maximum size, in bytes, of the data within the column.

maxTimeInQueue
number <milli-seconds> (AsyncMaxTimeInQueue) [ 0 .. 7200000 ]
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": {
    • "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,
  • "requestSize": 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:
(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
{
  • "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": {
    • "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
          }
        }
      ]
    },
  • "resultSize": 98,
  • "completedAt": "2019-08-24T14:15:22Z"
}

Get 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
{
  • "data": "e2lk...",
  • "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:
(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
{
  • "application/json": {
    • "resourceType": "Patient",
    • "id": "1",
    • "name": [
      • {
        • "use": "official",
        • "text": "Mr John Smith",
        • "family": "Smith",
        • "given": [
          • "John"
          ],
        • "prefix": [
          • "Mr"
          ]
        }
      ]
    }
}

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:
(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

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.

object (Command)
text
required
string

The SQL statement to execute or the name of the stored procedure to run.

executionMode
string (ExecutionMode)
Enum: "reader" "nonQuery" "scalar"

Selects between fetching data or writing to the database. reader executes the command (e.g. SELECT) and returns rows of data. nonQuery executes the command (e.g. UPDATE, INSERT, or DELETE) and does not return data. scalar returns first value of first row of query results. For Querys using RETURN @values please use returnValue Parameters.

type
string (CommandType)
Enum: "text" "storedProcedure"

Indicates how the text property is to be interpreted. text executes the SQL contained within the text property. storedProcedure calls the stored procedure named in the text property. storedProcedure is currently experimental.

Array of objects (Parameter)

Parameters are used to supply data to, or read outputs from, a stored procedure.

Responses

Request samples

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

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
{
  • "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. If successful, the response will be a 204 with no response body.

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
{
  • "error": {
    • "status": 400,
    • "statusText": "Bad Request",
    • "message": "Malformed SQL"
    }
}

Get registered query result

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
}