Query examples
Checking capabilities
As mentioned in the Capabilities page, which FHIR resources and features are supported for a practice depends on which version of Halo Link they have installed.
Fetching a practice's Capability Statement is also not dependent on the underlying PMS database, so it's a good way to check your connection to Halo Link without needing to touch the database.
Therefore we recommend pulling a practice's Capability Statement as a first step. For a practice with Halo GUID 1234, its Capability Statement can be fetched from:
https://api.haloconnect.io/integrator/sites/1234/fhir/R4/metadata
The following accordion contains an example Capability Statement. It only lists one resource (Patient) and some values such as the site's Halo GUID have been obscured.
Capability Statement example
Request: GET {{baseUrl}}/sites/{{haloGuid}}/fhir/R4/metadata
Response:
{
"resourceType": "CapabilityStatement",
"id": "{haloGuid}",
"version": "24.527.2795.0",
"name": "RestServer",
"status": "active",
"publisher": "Halo Connect Pty Ltd",
"contact": [
{
"telecom": [
{
"system": "url",
"value": "https://haloconnect.io"
},
{
"system": "email",
"value": "support@haloconnect.io"
}
]
}
],
"copyright": "All Rights Reserved",
"kind": "instance",
"software": {
"name": "BP/Halo FHIR Server",
"version": "24.527.2790+349a62d367f5a93c08802ececb813c36b4ff4bbe"
},
"implementation": {
"description": "Halo FHIR Server",
"url": "https://haloconnect.io"
},
"fhirVersion": "4.0.1",
"format": [
"application/fhir+json",
"application/json"
],
"patchFormat": [
""
],
"rest": [
{
"mode": "server",
"resource": [
{
"type": "Patient",
"profile": "http://hl7.org/fhir/StructureDefinition/Patient",
"supportedProfile": [
"http://hl7.org.au/fhir/StructureDefinition/au-patient"
],
"interaction": [
{
"code": "read"
}
],
"searchParam": [
{
"name": "_id",
"definition": "http://hl7.org/fhir/SearchParameter/Resource-id",
"type": "token",
"documentation": "Logical id of this artifact"
},
{
"name": "_lastUpdated",
"definition": "http://hl7.org/fhir/SearchParameter/Resource-lastUpdated",
"type": "date",
"documentation": "When the resource version last changed"
},
{
"name": "given",
"definition": "http://hl7.org/fhir/SearchParameter/individual-given",
"type": "string",
"documentation": "A portion of the given name of the patient"
},
{
"name": "family",
"definition": "http://hl7.org/fhir/SearchParameter/individual-family",
"type": "string",
"documentation": "A portion of the family name of the patient"
}
]
}
]
}
]
}
Get Patient by ID
The following query gets a Patient resource using its ID. The result is a single Patient resource.
Note the Practitioner reference at the end. The specified Practitioner ID can be used to get more information about that Practitioner.
Get Patient by ID
Request: GET {{baseUrl}}/sites/{{haloGuid}}/fhir/R4/Patient/pt-1
Response:
{
"resourceType": "Patient",
"id": "pt-1",
"meta": {
"lastUpdated": "2017-03-14T20:27:16+00:00",
"profile": [
"http://hl7.org.au/fhir/StructureDefinition/au-patient"
]
},
"extension": [
{
"url": "http://hl7.org.au/fhir/StructureDefinition/indigenous-status",
"valueCoding": {
"system": "https://healthterminologies.gov.au/fhir/CodeSystem/australian-indigenous-status-1",
"code": "9",
"display": "Not stated/inadequately described"
}
}
],
"identifier": [
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "MC",
"display": "Patient's Medicare Number"
}
],
"text": "Medicare Number"
},
"system": "http://ns.electronichealth.net.au/id/medicare-number",
"value": "12345678901",
"period": {
"end": "2024-12"
}
}
],
"active": true,
"name": [
{
"use": "official",
"text": "Miss Jane Ellen Doe",
"family": "Doe",
"given": [
"Jane",
"Ellen"
],
"prefix": [
"Miss"
]
},
{
"use": "usual",
"text": "Jane",
"given": [
"Jane"
]
}
],
"telecom": [
{
"system": "phone",
"value": "07 12345678",
"use": "home"
}
],
"gender": "female",
"birthDate": "1995-01-01",
"address": [
{
"use": "home",
"type": "physical",
"line": [
"1 Main St"
],
"city": "Brisbane",
"postalCode": "4000"
}
],
"generalPractitioner": [
{
"reference": "Practitioner/pr-1"
}
]
}
Search for Patients by exact family name
The following query searches for any Patients with exactly the family name "Doe" using the family search parameter. The result is a Bundle of two Patient resources.
Note this query uses the :exact parameter modifier to specify only Patients with exactly the family name "Doe". Otherwise, search would, by default, return any Patients whose family name starts with "Doe".
Search for Patients by family
Request: GET {{baseUrl}}/sites/{{haloGuid}}/fhir/R4/Patient?family:exact=doe
Response:
{
"resourceType": "Bundle",
"type": "searchset",
"total": 2,
"link": [
{
"relation": "self",
"url": "https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Patient/?family:exact=doe&_count=30&_offset=0"
},
{
"relation": "next",
"url": "https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Patient/?family:exact=doe&_count=30&_offset=30"
}
],
"entry": [
{
"fullUrl": "https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Patient/pt-1",
"resource": {
"resourceType": "Patient",
"id": "pt-1",
"meta": {
"lastUpdated": "2017-03-14T20:27:16+00:00",
"profile": [
"http://hl7.org.au/fhir/StructureDefinition/au-patient"
]
},
"extension": [
{
"url": "http://hl7.org.au/fhir/StructureDefinition/indigenous-status",
"valueCoding": {
"system": "https://healthterminologies.gov.au/fhir/CodeSystem/australian-indigenous-status-1",
"code": "9",
"display": "Not stated/inadequately described"
}
}
],
"identifier": [
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "MC",
"display": "Patient's Medicare Number"
}
],
"text": "Medicare Number"
},
"system": "http://ns.electronichealth.net.au/id/medicare-number",
"value": "12345678901",
"period": {
"end": "2024-12"
}
}
],
"active": true,
"name": [
{
"use": "official",
"text": "Miss Jane Ellen Doe",
"family": "Doe",
"given": [
"Jane",
"Ellen"
],
"prefix": [
"Miss"
]
},
{
"use": "usual",
"text": "Jane",
"given": [
"Jane"
]
}
],
"telecom": [
{
"system": "phone",
"value": "07 12345678",
"use": "home"
}
],
"gender": "female",
"birthDate": "1995-01-01",
"address": [
{
"use": "home",
"type": "physical",
"line": [
"1 Main St"
],
"city": "Brisbane",
"postalCode": "4000"
}
],
"generalPractitioner": [
{
"reference": "Practitioner/pr-1"
}
]
}
},
{
"fullUrl": "https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Patient/pt-2",
"resource": {
"resourceType": "Patient",
"id": "pt-1",
"meta": {
"lastUpdated": "2017-03-14T20:27:16+00:00",
"profile": [
"http://hl7.org.au/fhir/StructureDefinition/au-patient"
]
},
"extension": [
{
"url": "http://hl7.org.au/fhir/StructureDefinition/indigenous-status",
"valueCoding": {
"system": "https://healthterminologies.gov.au/fhir/CodeSystem/australian-indigenous-status-1",
"code": "9",
"display": "Not stated/inadequately described"
}
}
],
"identifier": [
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "MC",
"display": "Patient's Medicare Number"
}
],
"text": "Medicare Number"
},
"system": "http://ns.electronichealth.net.au/id/medicare-number",
"value": "12345678902",
"period": {
"end": "2024-12"
}
}
],
"active": true,
"name": [
{
"use": "official",
"text": "Mr John Alan Doe",
"family": "Doe",
"given": [
"John",
"Alan"
],
"prefix": [
"Mr"
]
},
{
"use": "usual",
"text": "John",
"given": [
"John"
]
}
],
"telecom": [
{
"system": "phone",
"value": "07 12345678",
"use": "home"
}
],
"gender": "male",
"birthDate": "1990-12-12",
"address": [
{
"use": "home",
"type": "physical",
"line": [
"1 Main St"
],
"city": "Brisbane",
"postalCode": "4000"
}
],
"generalPractitioner": [
{
"reference": "Practitioner/pr-1"
}
]
}
}
]
}
Search for Patients born after a given date
The following query shows how to use ordered parameter prefixes to search for Patients with birthdates from Jan 1 1994 onwards.
Note that the FHIR API currently requires dates to be specified in full. 1993-12-31 is valid, but 1993 and 1993-12 are not.
Search for Patients by birthdate range
Request: GET {{baseUrl}}/sites/{{haloGuid}}/fhir/R4/Patient?birthdate=gt1993-12-31
Response:
{
"resourceType": "Bundle",
"type": "searchset",
"total": 1,
"link": [
{
"relation": "self",
"url": "https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Patient/?birthdate=gt1993-12-31&_count=30&_offset=0"
},
{
"relation": "next",
"url": "https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Patient/?birthdate=gt1993-12-31&_count=30&_offset=30"
}
],
"entry": [
{
"fullUrl": "https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Patient/pt-1",
"resource": {
"resourceType": "Patient",
"id": "pt-1",
"meta": {
"lastUpdated": "2017-03-14T20:27:16+00:00",
"profile": [
"http://hl7.org.au/fhir/StructureDefinition/au-patient"
]
},
"extension": [
{
"url": "http://hl7.org.au/fhir/StructureDefinition/indigenous-status",
"valueCoding": {
"system": "https://healthterminologies.gov.au/fhir/CodeSystem/australian-indigenous-status-1",
"code": "9",
"display": "Not stated/inadequately described"
}
}
],
"identifier": [
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "MC",
"display": "Patient's Medicare Number"
}
],
"text": "Medicare Number"
},
"system": "http://ns.electronichealth.net.au/id/medicare-number",
"value": "12345678901",
"period": {
"end": "2024-12"
}
}
],
"active": true,
"name": [
{
"use": "official",
"text": "Miss Jane Ellen Doe",
"family": "Doe",
"given": [
"Jane",
"Ellen"
],
"prefix": [
"Miss"
]
},
{
"use": "usual",
"text": "Jane",
"given": [
"Jane"
]
}
],
"telecom": [
{
"system": "phone",
"value": "07 12345678",
"use": "home"
}
],
"gender": "female",
"birthDate": "1995-01-01",
"address": [
{
"use": "home",
"type": "physical",
"line": [
"1 Main St"
],
"city": "Brisbane",
"postalCode": "4000"
}
],
"generalPractitioner": [
{
"reference": "Practitioner/pr-1"
}
]
}
}
]
}
Sorting search results
The following query gets all Patients with the family name "Doe", but also sorts the results by birthdate. This returns John and Jane Doe in the opposite order, compared to only searching by their family name.
Search for Patients by family and sort by birthdate
Request: GET {{baseUrl}}/sites/{{haloGuid}}/fhir/R4/Patient?family:exact=doe&_sort=birthdate
Response:
{
"resourceType": "Bundle",
"type": "searchset",
"total": 2,
"link": [
{
"relation": "self",
"url": "https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Patient/?family:exact=doe&_count=30&_offset=0"
},
{
"relation": "next",
"url": "https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Patient/?family:exact=doe&_count=30&_offset=30"
}
],
"entry": [
{
"fullUrl": "https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Patient/pt-2",
"resource": {
"resourceType": "Patient",
"id": "pt-1",
"meta": {
"lastUpdated": "2017-03-14T20:27:16+00:00",
"profile": [
"http://hl7.org.au/fhir/StructureDefinition/au-patient"
]
},
"extension": [
{
"url": "http://hl7.org.au/fhir/StructureDefinition/indigenous-status",
"valueCoding": {
"system": "https://healthterminologies.gov.au/fhir/CodeSystem/australian-indigenous-status-1",
"code": "9",
"display": "Not stated/inadequately described"
}
}
],
"identifier": [
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "MC",
"display": "Patient's Medicare Number"
}
],
"text": "Medicare Number"
},
"system": "http://ns.electronichealth.net.au/id/medicare-number",
"value": "12345678902",
"period": {
"end": "2024-12"
}
}
],
"active": true,
"name": [
{
"use": "official",
"text": "Mr John Alan Doe",
"family": "Doe",
"given": [
"John",
"Alan"
],
"prefix": [
"Mr"
]
},
{
"use": "usual",
"text": "John",
"given": [
"John"
]
}
],
"telecom": [
{
"system": "phone",
"value": "07 12345678",
"use": "home"
}
],
"gender": "male",
"birthDate": "1990-12-12",
"address": [
{
"use": "home",
"type": "physical",
"line": [
"1 Main St"
],
"city": "Brisbane",
"postalCode": "4000"
}
],
"generalPractitioner": [
{
"reference": "Practitioner/pr-1"
}
]
}
},
{
"fullUrl": "https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Patient/pt-1",
"resource": {
"resourceType": "Patient",
"id": "pt-1",
"meta": {
"lastUpdated": "2017-03-14T20:27:16+00:00",
"profile": [
"http://hl7.org.au/fhir/StructureDefinition/au-patient"
]
},
"extension": [
{
"url": "http://hl7.org.au/fhir/StructureDefinition/indigenous-status",
"valueCoding": {
"system": "https://healthterminologies.gov.au/fhir/CodeSystem/australian-indigenous-status-1",
"code": "9",
"display": "Not stated/inadequately described"
}
}
],
"identifier": [
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "MC",
"display": "Patient's Medicare Number"
}
],
"text": "Medicare Number"
},
"system": "http://ns.electronichealth.net.au/id/medicare-number",
"value": "12345678901",
"period": {
"end": "2024-12"
}
}
],
"active": true,
"name": [
{
"use": "official",
"text": "Miss Jane Ellen Doe",
"family": "Doe",
"given": [
"Jane",
"Ellen"
],
"prefix": [
"Miss"
]
},
{
"use": "usual",
"text": "Jane",
"given": [
"Jane"
]
}
],
"telecom": [
{
"system": "phone",
"value": "07 12345678",
"use": "home"
}
],
"gender": "female",
"birthDate": "1995-01-01",
"address": [
{
"use": "home",
"type": "physical",
"line": [
"1 Main St"
],
"city": "Brisbane",
"postalCode": "4000"
}
],
"generalPractitioner": [
{
"reference": "Practitioner/pr-1"
}
]
}
}
]
}
_include multiple resources
Retrieve a Patient resource with id=1 and the Practitioner resource it references using the general-practitioner search parameter.
_include example
Request: GET {{baseUrl}}/sites/{{haloGuid}}/fhir/R4/Patient?_id=1&_include=Patient:general-practitioner
Response:
{
"resourceType": "Bundle",
"meta": {
"lastUpdated": "2024-08-19T00:23:12.3825033+00:00"
},
"type": "searchset",
"timestamp": "2024-08-19T00:23:12.3825033+00:00",
"total": 1,
"link": [
{
"relation": "self",
"url": "https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Patient?_id=pt-1&_count=30&_offset=0"
}
],
"entry": [
{
"fullUrl": "https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Patient/1",
"resource": {
"resourceType": "Patient",
"id": "pt-1",
...
"name": [
{
"use": "official",
"text": "Miss Anastasia Rose Carey",
"family": "Carey",
"given": [
"Anastasia",
"Rose"
],
"prefix": [
"Miss"
]
}
],
...
"generalPractitioner": [
{
"reference": "Practitioner/pr-1",
"type": "Practitioner"
}
]
},
"search": {
"mode": "match"
}
},
{
"fullUrl": "https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Practitioner/pr-1",
"resource": {
"resourceType": "Practitioner",
"id": "pr-1",
...
"name": [
{
"use": "official",
"text": "Dr Frederick Findacure",
"family": "Findacure",
"given": [
"Frederick"
],
"prefix": [
"Dr"
]
}
]
},
"search": {
"mode": "include"
}
}
]
}
_revinclude multiple resources
Retrieve a Practitioner resource with id=1 and the Patient resources which reference it using the general-practitioner search parameter.
_revinclude example
Request: GET {{baseUrl}}/sites/{{haloGuid}}/fhir/R4/Practitioner?_id=pr-1&_revinclude=Patient:general-practitioner
Response:
{
"resourceType": "Bundle",
"meta": {
"lastUpdated": "2024-08-19T00:27:56.0026201+00:00"
},
"type": "searchset",
"timestamp": "2024-08-19T00:27:56.0026201+00:00",
"total": 1,
"link": [
{
"relation": "self",
"url": "https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Practitioner/?_id=1&_count=30&_offset=0"
}
],
"entry": [
{
"fullUrl": "https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Practitioner/pr-1",
"resource": {
"resourceType": "Practitioner",
"id": "pr-1",
...
"name": [
{
"use": "official",
"text": "Dr Frederick Findacure",
"family": "Findacure",
"given": [
"Frederick"
],
"prefix": [
"Dr"
]
}
]
},
"search": {
"mode": "match"
}
},
{
"fullUrl": "https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Patient/pt-1",
"resource": {
"resourceType": "Patient",
"id": "pt-1",
...
"generalPractitioner": [
{
"reference": "Practitioner/1",
"type": "Practitioner"
}
]
},
"search": {
"mode": "include"
}
},
{
"fullUrl": "https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Patient/pt-3",
"resource": {
"resourceType": "Patient",
"id": "pt-3",
...
"generalPractitioner": [
{
"reference": "Practitioner/1",
"type": "Practitioner"
}
]
},
"search": {
"mode": "include"
}
},
...
]
}
Get all Locations
Requesting resources without specifying an ID or any search parameters will return all resources of that type.
Get all Locations example
Request: GET {{baseUrl}}/sites/{{haloGuid}}/fhir/R4/Location
Response:
{
"resourceType": "Bundle",
"type": "searchset",
"total": 11,
"link": [
{
"relation": "self",
"url": "http://halo/fhir?_page=1&_count=30"
},
{
"relation": "next",
"url": "http://halo/fhir?_page=2&_count=30"
}
],
"entry": [
{
"fullUrl": "1",
"resource": {
"resourceType": "Location",
"id": "clinloc-1",
"meta": {
"profile": [
"http://hl7.org.au/fhir/StructureDefinition/au-location"
]
},
"identifier": [
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org.au/CodeSystem/v2-0203",
"code": "LSPN",
"display": "Location Specific Practice Number"
}
],
"text": "LSPN"
},
"system": "http://ns.electronichealth.net.au/id/location-specific-practice-number",
"value": "100302"
}
],
"status": "active",
"name": "Some Medical Clinic",
"mode": "instance",
"telecom": [
{
"system": "phone",
"value": "0744444444",
"use": "work"
},
{
"system": "phone",
"value": "0444444444",
"use": "mobile"
},
{
"system": "fax",
"value": "0744444445",
"use": "work"
},
{
"system": "email",
"value": "info@someclinic.com.au",
"use": "work"
}
],
"address": {
"use": "work",
"type": "both",
"line": [
"1 Best Avenue"
],
"city": "Brisbane",
"postalCode": "4000"
},
"physicalType": {
"coding": [
{
"system": "http://terminology.hl7.org.au/ValueSet/location-physical-type-extended",
"code": "bu",
"display": "Building"
}
]
},
"managingOrganization": {
"reference": "Organization/clinloc-1",
"display": "Best Clinic"
}
}
},
{
"fullUrl": "2",
"resource": {
"resourceType": "Location",
"id": "clinloc-2",
"meta": {
"profile": [
"http://hl7.org.au/fhir/StructureDefinition/au-location"
]
},
"status": "active",
"name": "Some Other Clinic",
"mode": "instance",
"address": {
"use": "work",
"type": "both",
"line": [
"1 Nice Street"
],
"city": "Brisbane",
"postalCode": "4000"
},
"physicalType": {
"coding": [
{
"system": "http://terminology.hl7.org.au/ValueSet/location-physical-type-extended",
"code": "bu",
"display": "Building"
}
]
},
"managingOrganization": {
"reference": "Organization/clinloc-2",
"display": "Clinic"
}
}
}
]
}