# FHIR

The Platform API includes FHIR (Fast Healthcare Interoperability Resources) endpoints for workspaces with EHR integrations. These provide patient search, clinical timelines, resource CRUD, and data import.

{% hint style="warning" %}
**Requires FHIR configuration.** These endpoints are only available for workspaces with an EHR type and FHIR store URL configured. See [Workspaces](https://docs.amigo.ai/developer-guide/platform-api/platform-api/workspaces).
{% endhint %}

{% @mermaid/diagram content="%%{init: {"flowchart": {"useMaxWidth": true, "nodeSpacing": 20, "rankSpacing": 30}, "theme": "base", "themeVariables": {"primaryColor": "#D4E2E7", "primaryTextColor": "#100F0F", "primaryBorderColor": "#083241", "lineColor": "#575452", "textColor": "#100F0F", "clusterBkg": "#F1EAE7", "clusterBorder": "#D7D2D0"}}}%%
flowchart LR
subgraph EHR\["EHR System"]
FR\[FHIR Resources\nPatient, Appointment,\nEncounter, etc.]
end
CR\[Connector Runner]
subgraph WM\["World Model"]
WE\[Entities &\nRelationships]
end

```
FR -->|Inbound sync| CR
CR -->|Entity resolution\n& confidence scoring| WE
WE -->|Outbound sync| CR
CR -->|Resource updates| FR

style FR fill:#D4E2E7,stroke:#083241,color:#100F0F,stroke-width:2px
style CR fill:#F0DDD9,stroke:#AA412A,color:#100F0F,stroke-width:2px
style WE fill:#DDE3DB,stroke:#2c3827,color:#100F0F,stroke-width:2px" %}
```

## Capabilities

### Status & Sync

Check FHIR integration health, event counts, and recent sync failures.

### Patient Access

* **Search**: Find patients by name, identifier, or MRN
* **List**: Paginated patient list with `sort_by` parameter supporting `+/-` prefix for sort direction (e.g., `-last_event_at` for newest activity first, `+created_at` for oldest first)
* **Timeline**: View a patient's event history (visits, encounters, procedures)
* **Summary**: Get a structured clinical summary

### Resource CRUD

Full create, read, update operations on FHIR resources. Search by resource type with standard FHIR search parameters.

Resource responses include an `entity_id` field linking each FHIR resource to its corresponding world model entity. This enables direct navigation between FHIR resources and entity views without a separate lookup. The field is `null` when no entity link exists yet (e.g., newly created resources pending entity resolution).

### Resource History

`GET /fhir/resources/{resource_type}/{resource_id}/history` returns the version history for a single FHIR resource, ordered newest-first.

| Parameter | Type           | Default | Description       |
| --------- | -------------- | ------- | ----------------- |
| `limit`   | integer (1-50) | 10      | Page size         |
| `offset`  | integer        | 0       | Pagination offset |

Each entry includes the event metadata (`event_type`, `source`, `source_system`, `confidence`, `synced_at`, `sync_error`), the full resource `data` at that version, an `is_current` flag, and a `fields_affected` list of dot-path field names that changed compared to the previous version (e.g., `name.0.given`, `telecom.0.value`). The response includes `total`, `has_more`, and `next_offset` for pagination. Returns 404 if the resource has no events.

### Sync Failure Filtering

The sync failures endpoint supports scoped filtering to investigate issues with specific resources:

| Parameter            | Type            | Description                                                                       |
| -------------------- | --------------- | --------------------------------------------------------------------------------- |
| `fhir_resource_type` | string          | Filter failures to a specific FHIR resource type (e.g., `Patient`, `Appointment`) |
| `fhir_resource_id`   | string          | Filter failures to a specific FHIR resource ID                                    |
| `limit`              | integer (1-100) | Page size (default 50)                                                            |

The `total` field in the response reflects the filtered count, not just the page size.

### Bundle Import

Import a FHIR Bundle to upsert multiple resources in a single request - useful for bulk data loads and system migrations.

## API Reference

* [FHIR](https://docs.amigo.ai/api-reference/readme/platform/fhir)