The Halo Cloud API for desktop applications, exposing a token endpoint plus SQL passthrough, FHIR R4 resource search, and registered-query operations under the /desktop path. Authenticated with an Azure API Management subscription key, a bearer JWT, and a device identifier header.
{
"openapi": "3.1.1",
"info": {
"version": "26.619.10213",
"title": "Halo Cloud API for Desktop Applications",
"contact": {
"email": "support@haloconnect.io"
},
"license": {
"name": "Copyright © Halo Connect 2023",
"url": "http://haloconnect.io"
},
"x-logo": {
"url": "https://20496383.fs1.hubspotusercontent-na1.net/hubfs/20496383/halo_logo%20(1).png",
"altText": "Halo Connect Logo"
},
"description": "## Introduction\nThis API reference documents the endpoints available for desktop application integration with the Halo Connect Cloud API. It covers:\n\n- **Tokens** – Obtain authorization tokens for desktop applications\n- **SQL Passthrough** – Execute SQL queries against site databases\n- **FHIR** – Query practice data using FHIR resources\n- **Registered Queries** – Execute recurring SQL queries against practice databases\n\nFor more information about Halo Connect, visit our [website](https://haloconnect.io) or [blog](https://haloconnect.io/blog).\n\n## Prerequisites\n\nAll API endpoints require an active pairing with the target site. Use the [Pair with a site](./integrator#operation/Integrator_PairSite) endpoint to establish access before making queries.\n\n## Definitions\n\nFor detailed documentation and guides, see our [documentation portal](https://docs.haloconnect.io).\n\n- **Site:** An instance of Halo Link connected to a practice's PMS database.\n- **Halo GUID:** A unique identifier for a site, used by Halo Connect to route queries.\n"
},
"servers": [
{
"url": "https://api.haloconnect.io",
"description": "Production"
},
{
"url": "https://api.stage.haloconnect.io",
"description": "Stage"
}
],
"tags": [
{
"name": "Tokens",
"description": "Obtain authorization tokens for desktop applications to authenticate API requests."
},
{
"name": "SQL Passthrough",
"description": "Send SQL queries to practices as immediate, async or registered queries.\n\n**Immediate queries** are small, time-sensitive queries that return a result in seconds. Response size is limited to 8MB.\n\n**Async queries** are queued for execution and results can be retrieved later. The workflow is:\n\n 1. **Submit async query** – Creates a query and returns a `queryId` on success.\n 2. **Get query status** – Check query status. When complete, includes pagination details.\n 3. **Get query result page** – Retrieve result pages using the pagination info from the status response.\n\n**Registered Queries** are also supported. See the [Registered Queries](#tag/Registered-Queries) section for more information.\n"
},
{
"name": "FHIR",
"description": "Query practice data using FHIR resources."
}
],
"paths": {
"/integrator/token": {
"post": {
"tags": [
"Tokens"
],
"summary": "Get authorization token",
"description": "This endpoint enables integrators to obtain an authorization token for a specific desktop application associated with a given Halo GUID.\nThe token is required to authenticate subsequent requests to the SQL Passthrough or FHIR for that desktop application.\n",
"operationId": "obtainToken",
"requestBody": {
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"properties": {
"grant_type": {
"type": "string",
"enum": [
"urn:halo-connect:oauth:desktop-token"
],
"description": "Must be set to urn:halo-connect:oauth:desktop-token"
},
"device_id": {
"type": "string",
"description": "The unique identifier of the device"
},
"site_id": {
"type": "string",
"description": "The Halo GUID of the site"
}
},
"required": [
"grant_type",
"device_id",
"site_id"
]
},
"example": {
"grant_type": "urn:halo-connect:oauth:desktop-token",
"device_id": "example-device-123",
"site_id": "example-site-guid"
}
}
}
},
"responses": {
"200": {
"description": "Token successfully obtained",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"access_token": {
"type": "string"
},
"token_type": {
"type": "string"
},
"expires_in": {
"type": "integer"
}
}
}
}
}
},
"400": {
"description": "Invalid request"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not found"
},
"415": {
"description": "Unsupported media type"
}
},
"security": [
{
"SubscriptionKey": []
}
]
}
},
"/desktop/sites/{siteId}/queries/immediate": {
"post": {
"tags": [
"SQL Passthrough"
],
"summary": "Execute immediate query",
"description": "Send an immediate query to a site and receive the result in the response.\n\nQuery status can also be retrieved using the **Get query status** endpoint.\n",
"operationId": "createImmediateQuery",
"parameters": [
{
"name": "siteId",
"in": "path",
"description": "Halo GUID of the site.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Immediate query executed.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"required": [
"id",
"integratorId",
"siteId",
"mode",
"status",
"maxTimeInQueue",
"commandSize",
"createdAt",
"updatedAt",
"requestSize"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the entity."
},
"integratorId": {
"type": "string",
"format": "uuid",
"description": "Id of the Integrator that created the query."
},
"siteId": {
"type": "string",
"format": "uuid",
"description": "Halo GUID of the site."
},
"mode": {
"type": "string",
"enum": [
"immediate"
]
},
"maxTimeInQueue": {
"type": "integer",
"format": "milli-seconds",
"example": 15000,
"minimum": 0,
"maximum": 60000,
"default": 30000
},
"commandSize": {
"type": "integer",
"example": 98
},
"requestSize": {
"type": "integer",
"example": 98
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"successful"
]
},
"statusTiming": {
"allOf": [
{
"type": "object",
"description": "The server time (UTC) at which a query entered and exited the various states.",
"properties": {
"initialising": {
"properties": {
"startTime": {
"type": "string",
"format": "date-time"
}
},
"required": [
"startTime"
]
},
"executing": {
"properties": {
"startTime": {
"type": "string",
"format": "date-time"
}
}
},
"downloading": {
"properties": {
"startTime": {
"type": "string",
"format": "date-time"
}
}
},
"uploading": {
"properties": {
"startTime": {
"type": "string",
"format": "date-time"
}
}
}
},
"required": [
"initialising",
"executing"
]
}
]
},
"metrics": {
"type": "object",
"required": [
"sqlExecutionDuration"
],
"properties": {
"sqlExecutionDuration": {
"type": "integer",
"example": 1000,
"description": "The number of milli-seconds from when Halo Link Service sends a query to the database until it gets a response."
}
}
},
"result": {
"oneOf": [
{
"type": "object",
"required": [
"rows",
"size",
"data"
],
"properties": {
"rows": {
"type": "integer",
"example": 30
},
"size": {
"type": "integer",
"example": 25
},
"data": {
"type": "string",
"format": "base64",
"description": "Result data that is base64 encoded returned from the executed query.",
"example": "e2lk..."
},
"parameters": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "@siteid",
"description": "The name of the parameter."
},
"direction": {
"description": "A value that indicates whether the parameter is input-only, output-only, bidirectional, or a stored procedure return value parameter.",
"type": "string",
"enum": [
"output",
"input",
"inputOutput",
"returnValue"
]
},
"type": {
"description": "Specifies SQL Server-specific data type of a field, property.",
"type": "string",
"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"
]
},
"value": {
"description": "Gets or sets the value of the parameter.",
"type": [
"string",
"null"
],
"format": "base64 (output)",
"example": "66"
},
"size": {
"description": "The maximum size, in bytes, of the data within the column.",
"type": "integer",
"example": 43
}
}
}
}
}
},
{
"type": "object",
"required": [
"rowsAffected",
"size"
],
"properties": {
"rowsAffected": {
"type": "integer",
"example": 30
},
"size": {
"type": "integer",
"example": 25
},
"parameters": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "@siteid",
"description": "The name of the parameter."
},
"direction": {
"description": "A value that indicates whether the parameter is input-only, output-only, bidirectional, or a stored procedure return value parameter.",
"type": "string",
"enum": [
"output",
"input",
"inputOutput",
"returnValue"
]
},
"type": {
"description": "Specifies SQL Server-specific data type of a field, property.",
"type": "string",
"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"
]
},
"value": {
"description": "Gets or sets the value of the parameter.",
"type": [
"string",
"null"
],
"format": "base64 (output)",
"example": "66"
},
"size": {
"description": "The maximum size, in bytes, of the data within the column.",
"type": "integer",
"example": 43
}
}
}
}
}
}
]
},
"resultSize": {
"type": "integer",
"example": 98
},
"completedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"statusTiming",
"metrics",
"result",
"completedAt"
]
}
]
}
}
}
},
"400": {
"description": "Bad Request - Invalid request path, parameter or body.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"format": "httpStatus"
},
"statusText": {
"type": "string",
"format": "httpStatusPhrase"
},
"message": {
"type": "string"
}
}
}
}
},
{
"allOf": [
{
"type": "object",
"required": [
"id",
"integratorId",
"siteId",
"mode",
"status",
"maxTimeInQueue",
"commandSize",
"createdAt",
"updatedAt",
"requestSize"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the entity."
},
"integratorId": {
"type": "string",
"format": "uuid",
"description": "Id of the Integrator that created the query."
},
"siteId": {
"type": "string",
"format": "uuid",
"description": "Halo GUID of the site."
},
"mode": {
"type": "string",
"enum": [
"immediate"
]
},
"maxTimeInQueue": {
"type": "integer",
"format": "milli-seconds",
"example": 15000,
"minimum": 0,
"maximum": 60000,
"default": 30000
},
"commandSize": {
"type": "integer",
"example": 98
},
"requestSize": {
"type": "integer",
"example": 98
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"executionFailed"
]
},
"statusTiming": {
"example": {
"statusTiming": {
"initialising": {
"startTime": "2019-08-24T14:15:22.847Z"
},
"executing": {
"startTime": "2019-08-24T14:15:22.847Z"
}
}
},
"type": "object",
"description": "The server time (UTC) at which a query entered and exited the various states.",
"properties": {
"initialising": {
"properties": {
"startTime": {
"type": "string",
"format": "date-time"
},
"endTime": {
"type": "string",
"format": "date-time"
}
},
"required": [
"startTime"
]
},
"queued": {
"properties": {
"startTime": {
"type": "string",
"format": "date-time"
},
"endTime": {
"type": "string",
"format": "date-time"
}
}
},
"executing": {
"properties": {
"startTime": {
"type": "string",
"format": "date-time"
},
"endTime": {
"type": "string",
"format": "date-time"
}
}
},
"uploading": {
"properties": {
"startTime": {
"type": "string",
"format": "date-time"
},
"endTime": {
"type": "string",
"format": "date-time"
}
}
}
},
"required": [
"initialising"
]
},
"errorCode": {
"deprecated": true,
"type": "integer"
},
"errorMessage": {
"deprecated": true,
"type": "string"
},
"errorDetails": {
"type": "object",
"properties": {
"errorType": {
"type": "string",
"enum": [
"http",
"mssql",
"fbsql",
"haloLink"
]
},
"errorCode": {
"type": "integer"
},
"errorMessage": {
"type": "string"
}
}
},
"completedAt": {
"type": "string",
"format": "date-time"
}
}
}
]
}
]
}
}
}
},
"401": {
"description": "Unauthorized request.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"format": "httpStatus"
},
"statusText": {
# --- truncated at 32 KB (597 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/halo-connect/refs/heads/main/openapi/halo-connect-desktop-openapi.json