Halo Connect
Halo Cloud API for Integrators

The Halo Cloud API for third-party software integrators to query on-premise practice management system databases over the cloud, covering site pairing, SQL passthrough (immediate and async queries), FHIR R4 resource search, and registered (recurring) queries. Authenticated with an Azure API Management subscription key.
Documentation GitHub OpenAPI
OpenAPI Specification

{
  "openapi": "3.1.1",
  "info": {
    "version": "26.619.10213",
    "title": "Halo Cloud API for Integrators",
    "contact": {
      "name": "Halo Connect Support",
      "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 to integrators using the Halo Connect Cloud API. It covers:\n\n- **Sites** – Retrieve site metadata and onboarding information\n- **SQL Passthrough** – Execute SQL queries against practice 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](#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- **PMS:** Practice Management Software.\n- **PMS ID:** The identifier assigned to a site by the PMS vendor.\n"
  },
  "servers": [
    {
      "url": "https://api.haloconnect.io",
      "description": "Production"
    },
    {
      "url": "https://api.stage.haloconnect.io",
      "description": "Stage"
    }
  ],
  "security": [
    {
      "SubscriptionKey": []
    }
  ],
  "tags": [
    {
      "name": "Sites",
      "description": "Endpoints for practice onboarding and site metadata."
    },
    {
      "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 practices using FHIR resources."
    },
    {
      "name": "Registered Queries",
      "description": "Recurring queries that run at a specified frequency, and can be used to monitor for updates or new records. This type is recommended for polling use cases."
    }
  ],
  "paths": {
    "/integrator/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": {
                              "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":

# --- truncated at 32 KB (711 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/halo-connect/refs/heads/main/openapi/halo-connect-integrator-openapi.json
Halo Cloud API for Integrators

Documentation

Specifications

Other Resources

OpenAPI Specification
