Halo Cloud FHIR API

{
  "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