---
title: "FHIR API"
url: "https://docs.unified.to/fhir/overview"
description: "Unified.to's FHIR API serves read-only HL7 FHIR R4 (4.0.1) endpoints over its Healthcare integrations. A FHIR client can search and read patients, practitioners, encounters, observations, conditions, allergies, medication requests, immunizations and diagnostic reports from a connected EHR, lab or practice management system, including systems that don't offer a FHIR API themselves. It's available on every plan."
---
# FHIR API

Unified.to's FHIR API serves read-only [HL7 FHIR R4](https://hl7.org/fhir/R4/) (4.0.1) endpoints over its Healthcare integrations. A FHIR client can search and read patients, practitioners, encounters, observations, conditions, allergies, medication requests, immunizations and diagnostic reports from a connected EHR, lab or practice management system, including systems that don't offer a FHIR API themselves. It's available on every plan.

## [How does FHIR map onto Healthcare integrations?](https://docs.unified.to/fhir/overview.md#how-does-fhir-map-onto-healthcare-integrations)

Each FHIR call is translated into the connected integration's own API at request time, through the matching Healthcare object, and the result is returned as a FHIR resource. FHIR works on any Healthcare integration; there's no separate FHIR integration to activate. Activate the Healthcare integrations you need and create connections as usual.

| FHIR resource      | Healthcare object |
| ------------------ | ----------------- |
| Patient            | Patient           |
| Practitioner       | Practitioner      |
| Encounter          | Encounter         |
| Observation        | Observation       |
| Condition          | Condition         |
| AllergyIntolerance | Allergy           |
| MedicationRequest  | Medication        |
| Immunization       | Immunization      |
| DiagnosticReport   | Report            |

What works depends on the integration:

* **Search** works wherever the integration lists the object, and **read** wherever it gets it by ID.
* Each connection's CapabilityStatement (`GET /fhir/{connection_id}/metadata`) lists the resources, interactions and search parameters its integration supports, including search parameters the integration requires (some integrations only list clinical records for one patient at a time).
* A resource type the facade doesn't serve, or a search the integration doesn't support, returns an `OperationOutcome` with status **404** and code `not-supported`.

Each integration's Feature Support tab lists its Healthcare objects and methods.

## [Endpoints](https://docs.unified.to/fhir/overview.md#endpoints)

| Resource            | Method | Path                                           | Operation                   |
| ------------------- | ------ | ---------------------------------------------- | --------------------------- |
| CapabilityStatement | GET    | /fhir/{connection\_id}/metadata                | Get the CapabilityStatement |
| Patient             | GET    | /fhir/{connection\_id}/Patient                 | Search patients             |
| Patient             | GET    | /fhir/{connection\_id}/Patient/{id}            | Read a patient              |
| Practitioner        | GET    | /fhir/{connection\_id}/Practitioner            | Search practitioners        |
| Practitioner        | GET    | /fhir/{connection\_id}/Practitioner/{id}       | Read a practitioner         |
| Encounter           | GET    | /fhir/{connection\_id}/Encounter               | Search encounters           |
| Encounter           | GET    | /fhir/{connection\_id}/Encounter/{id}          | Read an encounter           |
| Observation         | GET    | /fhir/{connection\_id}/Observation             | Search observations         |
| Observation         | GET    | /fhir/{connection\_id}/Observation/{id}        | Read an observation         |
| Condition           | GET    | /fhir/{connection\_id}/Condition               | Search conditions           |
| Condition           | GET    | /fhir/{connection\_id}/Condition/{id}          | Read a condition            |
| AllergyIntolerance  | GET    | /fhir/{connection\_id}/AllergyIntolerance      | Search allergies            |
| AllergyIntolerance  | GET    | /fhir/{connection\_id}/AllergyIntolerance/{id} | Read an allergy             |
| MedicationRequest   | GET    | /fhir/{connection\_id}/MedicationRequest       | Search medication requests  |
| MedicationRequest   | GET    | /fhir/{connection\_id}/MedicationRequest/{id}  | Read a medication request   |
| Immunization        | GET    | /fhir/{connection\_id}/Immunization            | Search immunizations        |
| Immunization        | GET    | /fhir/{connection\_id}/Immunization/{id}       | Read an immunization        |
| DiagnosticReport    | GET    | /fhir/{connection\_id}/DiagnosticReport        | Search diagnostic reports   |
| DiagnosticReport    | GET    | /fhir/{connection\_id}/DiagnosticReport/{id}   | Read a diagnostic report    |

Send your Unified.to API key as a bearer token (`Authorization: Bearer <token>`). Responses use the `application/fhir+json` media type. The OpenAPI file is [openapi-fhir.json](https://api.unified.to/docs/openapi-fhir.json).

## [Which search parameters are supported?](https://docs.unified.to/fhir/overview.md#which-search-parameters-are-supported)

* `_count`: page size. It defaults to, and is capped at, the integration's maximum page size.
* `_offset`: the paging offset. Searches return a `searchset` Bundle; follow its `next` link for the next page. `total` is set when the integration reports a total.
* `_lastUpdated`: resources updated at or after a time, with the `ge` prefix only (for example `_lastUpdated=ge2024-01-01T00:00:00Z`).
* `_id`: one resource by ID, as a Bundle with that resource or an empty Bundle.
* `patient` or `subject`: one patient, as `Patient/{id}` or `{id}`, on Encounter, Observation, Condition, AllergyIntolerance, MedicationRequest, Immunization and DiagnosticReport.
* `category` on Observation: an [observation category](https://terminology.hl7.org/CodeSystem-observation-category.html) code such as `vital-signs` or `laboratory`, optionally as `system|code`.

A search parameter the API recognizes but can't serve as asked returns an `OperationOutcome` with status **400**, rather than different results: another `_lastUpdated` prefix, several values for one parameter, or a modifier such as `:missing`. Other parameters are ignored and left out of the Bundle's `self` link, as FHIR allows; send `Prefer: handling=strict` to get a 400 for them instead.

## [How complete is the data?](https://docs.unified.to/fhir/overview.md#how-complete-is-the-data)

Resources are built from the Healthcare objects, so they carry the data those objects carry:

* They're valid FHIR R4 base resources, filled the way [US Core](https://hl7.org/fhir/us/core/) expects where the data exists (US Core race and ethnicity extensions, condition categories, identifier types). They don't declare US Core profiles.
* A DiagnosticReport links its results (`result`), patient (`subject`) and responsible practitioners (`performer`) as references, so a client can read the report and then each Observation, Patient and Practitioner it points to.
* An element FHIR requires that the integration doesn't provide is sent with the [data-absent-reason](https://hl7.org/fhir/R4/extension-data-absent-reason.html) extension instead of a guessed value. For example, MedicationRequest `intent` is always sent this way.
* For integrations that use FHIR themselves, extensions and codings the Healthcare objects don't carry aren't passed through. Use the [Passthrough API](https://docs.unified.to/passthrough/overview.md) to get the integration's own resources unchanged.

## [Does the FHIR API send webhooks?](https://docs.unified.to/fhir/overview.md#does-the-fhir-api-send-webhooks)

No. The FHIR API doesn't send webhooks. To find out when records change, subscribe to Healthcare webhooks on supported integrations.

## [Limits](https://docs.unified.to/fhir/overview.md#limits)

* Read-only: search and read. Create, update and delete aren't available through the FHIR API.
* SMART on FHIR authorization isn't available yet; authenticate with a Unified.to API key.
* Unified.to keeps no customer records at rest; connection credentials and operational metadata are encrypted at rest.

## [See also](https://docs.unified.to/fhir/overview.md#see-also)

* [Healthcare API](https://docs.unified.to/healthcare/overview.md)
* [Supported Healthcare integrations](https://docs.unified.to/healthcare/integrations.md)
