Capabilities

This page documents the high-level capabilities of the FHIR API, and how to find more information about what functionality is available for the supported PMSs.

Supported PMS

The FHIR API currently supports the following PMSs:

PMS	More info
Bp Premier	See the Best Practice Premier Knowledge Base

API versions

The FHIR API's FHIR translation engine is shipped as part of Halo Link, our local agent that connects PMS databases to our Halo Cloud APIs. As such, the version of the API available at a given practice depends on which version of Halo Link they have installed.

Due to Halo Link's auto-updater, most practices stay up to date, so version differences should rarely be a problem. However, some practices choose to delay updates or update manually, in which case they may be running an older version of the Link, and therefore an older version of the FHIR API.

To check which API version is available for a given practice:

Check the version field of the Capability Statement for that practice.
Use the Get status API endpoint to check the haloLinkVersion installed at the practice.

Capability statement

The FHIR specification defines a Capability Statement, which is used to document the capabilities of a FHIR server or facade. This is the best source for detailed information regarding the capabilities of the FHIR API, including which resources are implemented and exactly which search fields are available for each.

This documentation page is designed to supplement the Capability Statement with higher-level information. It does not duplicate or replace the information in the Capability Statement.

The Capability Statement for the FHIR API is available at: {baseUrl}/metadata

For example, in Production, to get the Capability Statement for a practice with a given {haloGUID}, the URI would be:

https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/metadata

See the FHIR specification for the Capability Statement resource for more information.

Available resources

The FHIR API may support a different set of resources for each supported PMS. For a list of which resources are supported for a given PMS, please check the relevant PMS's docs.

Resource ID prefixes

Resource IDs for the FHIR API are composite IDs of the format {letters}-{numbers}. For example, an ID for a Patient resource could be pt-1.

In order to allow the FHIR API to be used in conjunction with the SQL Passthrough API, the {number} suffix deterministically reflects specific database data.

However, because PMS databases and FHIR do not map one-to-one, some resources have multiple possible {letter} prefixes. This avoids ID number collisions by differentiating PMS database data that comes from different sources but maps to the same FHIR resource.

If you are using both the FHIR API and the SQL Passthrough and want more information about how to translate resource IDs to database IDs and vice versa, please contact Support.

Resource ID prefixes may differ between PMSs due to differences in the database data. For details of the resource ID prefixes for a given PMS, please see the relevant PMS's docs.

Bundles

When searching for a resource, multiple results may be returned as a bundle. For example, if searching for Patients named John Smith, there is a high chance of finding multiple records, which would be returned as a bundle containing multiple Patients. A valid search with no results will return an empty bundle.

See the Bundle resource documentation for more information.

Pagination

Bundles are paginated to help manage response size. There are two parameters for controlling page size and offset:

Result parameter	Description
_count	Specifies the number of results to show per page. Default is 30.
_offset	Specifies the number of results to skip over.

For example:

{baseUrl}Patient?_count=3 would return pages containing 3 resources each.
{baseUrl}Patient?_offset=5 would return pages of default size and skip the first 5 resources in the result set.
{baseUrl}Patient?_count=3&_offset=5 would return pages containing 3 resources and skip the first 5 resources in the result set.

Navigating pages can be done by using the URLs listed in the link array at the top of the Bundle resource, which give the search URLs for the current page (self), next, and previous pages.

Sorting is applied before pagination to ensure consistent results.

The following gets all Patients, but specifies pages should have three results and should start at the third result (skipping over the first two).

Bundle pagination example - first page

Request: https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Patient?_count=3&_offset=2

Response:

{
    "resourceType": "Bundle",
    "type": "searchset",
    "total": 39,
    "link": [
        {
        "relation": "self",
        "url": "https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Patient/?_count=3&_offset=2"
        },
        {
        "relation": "next",
        "url": "https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Patient/?_count=3&_offset=5"
        }
    ],
    "entry": [
        {
        "fullUrl": "https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Patient/pt-3",
        "resource": {
            "resourceType": "Patient",
            "id": "pt-3",
            ...
        },
        {
        "fullUrl": "https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Patient/pt-4",
        "resource": {
            "resourceType": "Patient",
            "id": "pt-4",
            ...
        },
        {
        "fullUrl": "https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Patient/pt-5",
        "resource": {
            "resourceType": "Patient",
            "id": "pt-5",
            ...
        },
    ]
}

To fetch the next page, use the URL supplied in link.

Since _count is now less than _offset, a URL is also included for the previous page.

Bundle pagination example - second page

Request: https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Patient?_count=3&_offset=5

Response:

{
    "resourceType": "Bundle",
    "type": "searchset",
    "total": 39,
    "link": [
        {
        "relation": "self",
        "url": "https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Patient/?_count=3&_offset=5"
        },
        {
        "relation": "next",
        "url": "https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Patient/?_count=3&_offset=8"
        },
        {
        "relation": "previous",
        "url": "https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Patient/?_count=3&_offset=2"
        }
    ],
    "entry": [
        {
        "fullUrl": "https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Patient/pt-6",
        "resource": {
            "resourceType": "Patient",
            "id": "pt-6",
            ...
        },
        {
        "fullUrl": "https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Patient/pt-7",
        "resource": {
            "resourceType": "Patient",
            "id": "pt-7",
            ...
        },
        {
        "fullUrl": "https://api.haloconnect.io/integrator/sites/{haloGuid}/fhir/R4/Patient/pt-8",
        "resource": {
            "resourceType": "Patient",
            "id": "pt-8",
            ...
        },
    ]
}

Search capabilities

Search parameters are available on a per-resource basis. Please see the capability statement or the relevant PMS's docs to check which search parameters are available for each resource.

FHIR API is case sensitive

Please note the FHIR API's URI is case sensitive. This applies to both the base URI (e.g. R4 must be capitalised) and parameters (e.g. _lastUpdated must have a capital U).

Which search parameters are available for each resource has been based on known use cases. More may be added over time. To request further search parameters, please contact support for the relevant PMS provider.

To check what possible search parameters FHIR defines for each resource, please see the FHIR Search Parameters registry. This lists all of the defined search parameters a FHIR API might implement. For the FHIR API, some parameters may not be possible and the implementation effort for the rest varies. However, anything requested from this list for supported resources will be given due consideration.

Searching for multiple values

When constructing a search query, the FHIR specification specifies that joining two parameters with & should be treated as an AND operation by the FHIR server or facade, and that comma-separated values should be treated as an OR operation.

More information can be found in the FHIR Search docs. The FHIR API aligns with the R4 FHIR specification, however the R5 FHIR search documentation is clearer on this particular topic.

Operation	Character	Description	Example
AND	`&`	Only return results which satisfy both parameters.	`{api}/Patient?given=John&birthday=gt1950-01-01` would only return Patients whose given names (first or middle name) contain John and whose birthdate is greater than Jan 1, 1950.
OR	`,`	Return all results which satisfy any listed value.	`{api}/Patient?given=John,Jane` would return all Patients whose given names (first or middle name) contain John or Jane.

Common search parameters

FHIR defines several search parameters which, if implemented, should apply to all resources. The following defines the availability of each in the FHIR API.

Descriptions are largely taken from the R4 FHIR Search docs.

Supported or planned

The following parameters are either currently supported or will be supported in an upcoming release.

Parameter	Description	Status
_id	Search by resource id (not a full URL).	Available
_lastUpdated	Search by date last updated.	Available
_has	Supports reverse chaining (selecting resources based on the resources which refer to them).	Partial support planned

Unsupported common parameters - click to expand

The following search parameters are unlikely to be supported as they are currently not applicable to the FHIR API, either due to technical limitations or dependencies which have not yet been implemented.

Parameter	Description	Reason
_list	Search all resources in nominated list (by id, not a full URL).	No List resources have been implemented yet.
_type	Define resource type(s) when executing a global search.	No known use cases.
_tag	Search by a resource tag.	The required data does not exist in the PMS database.
_security	Search by a security label.	The required data does not exist in the PMS database.
_profile	Search for all resources tagged with a profile.	The FHIR API only implements one profile per resource.
_text	Text search against the narrative.	The FHIR API does not generate narratives for resources.
_content	Text search against the entire resource.	Full text search not available.

Managing returned resources

FHIR defines several search parameters that can be used to modify the result that is returned by a search. The following lists the search result parameters currently available in the FHIR API.

Descriptions are largely taken from the R4 FHIR Search docs.

Result parameter	Description	Status
_sort	Order to sort results in.	Available
_count	Number of results per page.	Available in Bundles

Sorting results

Sorting is applied before pagination to ensure consistent results.

Use - to reverse the sort order. For example, Patient?_sort=family will sort results in alphabetical order (A to Z) by family name. Patient?_sort=-family will sort results by reverse alphabetical order (Z to A).

_sort currently works for any parameter a given resource can be searched for by, as specified in the Capability Statement. For example, you can both search for and sort Patients by their given name, family name, or birthdate.

See the Examples page for an example of sorting Patients by birthdate.

Including other resources

_include and _revinclude can be used to retrieve extra resources related to the results of a search, by joining on reference search parameters. To check which search parameters can be used with _include and _revinclude currently, check the searchInclude and searchRevInclude fields for the relevant resource in the Capability Statement.

Parameter	Description
`_include`	Allows you to specify additional resources to return where referenced by resources in the search results.
`_revinclude`	Allows you to specify additional resources to return which reference the resources in the search results.

For example, a Patient resource may contain a reference to a Practitioner under the generalPractitioner field. The search parameter for this field is general-practitioner. Some examples of how this could be used are:

To retrieve a Patient with id=1 and its referenced Practitioner: {api}/Patient?_id=pt-1&_include=Patient:general-practitioner.
To retrieve a Practitioner with id=1 and any Patients which reference it: {api}/Practitioner?_id=pr-1&_revinclude=Patient:general-practitioner
To retrieve Patients born after Jan 1, 1990 and their referenced Practitioners: {api}/Patient?birthdate=gt1990-01-01&_include=Patient:general-practitioner

See the R4 FHIR specification for more examples and explanations.

See the Examples page for examples of the Bundles returned by _include and _revinclude. Two key features are:

The total field in the Bundle metadata only counts resources in the original search results, not any that are included based on references.
Resources in the resulting bundle can be identified as either search results or referenced resources by the search.mode field, which will equal match for resources returned by the search and include for the included resources.

This functionality currently does not support:

:iterate
* wildcards

Advanced search options

The following enable integrators to further refine their search queries.

Parameter modifiers

The FHIR specification defines various search modifiers for each parameter type. The following lists the search modifiers that are currently available in the FHIR API.

Parameter type	Modifier	Description
String	`:exact`	Search string must match the result string exactly.
String	`:contains`	Search string can appear anywhere in the result string.

String search defaults to "starts with" behaviour. That is, the result string must start with the search string, but can contain any extra characters after.

See the Examples page for an example of using :exact when searching for Patients by their family name.

Ordered parameter prefixes

The FHIR specification defines nine prefixes for use with numbers, dates, and quantities, which enable functionality such as searching before or after a certain date. More information can be found in the FHIR Search docs.

The FHIR API currently implements:

Eight of the nine prefixes: ge, le, gt, lt, eq, ne, sa, and eb.
- ap is not implemented.
Support for dates only.
- Numbers and quantities are currently not supported.

See the Examples page for an example of using gt to find Patients born after a given date.

Unsupported advanced parameters

The following advanced search parameters are not supported:

_query
_filter
_format
_pretty

Filtering of database data

For some resources, the FHIR API will not return all of the records or columns that exist in the PMS database. This is usually to filter out PII or records which are no longer active or valid.

To clarify what data is returned or to request access to more data, please contact support for the relevant PMS provider.

References and resolvability

Many FHIR resources link to other resources via references. For example, a Patient resource is likely to link to a Practitioner resource via the generalPractitioner field.

As the FHIR API is a FHIR facade on top of a PMS database, information for referenced resources often exists in other database tables. Fetching this data, either to display it or validate the data forms a valid resource may require SQL JOINs and such which would affect the complexity and performance of the API.

In the interests of delivering the best performance, references therefore:

May not contain display fields or any extra context, to avoid surfacing PII.
May refer to data which, when fetched, does not resolve as it is not a valid resource due to filtering.

There may be exceptions, particularly where such data can be returned or validated without performance impacts.

Therefore, we recommend that when you need to rely on references, please:

Validate references by fetching their resources as well.
- For example, fetching a Patient's referenced Practitioner to ensure they are still an active employee of the practice.
Cache resources, or at least their validity, when possible.
- For example, caching which Practitioners are active for some number of days, so that they do not have to be fetched for every Patient resource.

Prev: FHIR API overview Next: FHIR API query examples