Skip to content

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/api/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.

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

_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.

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