# 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](/developer-guide/platform-api/platform-api/workspaces.md).
{% endhint %}

```mermaid
%%{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 a `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.

### Scheduling Access

* **Location views**: list facility-level Locations with address, phone, and hours of operation.
* **Slot views**: list bookable Slots with start, end, status, and the provider display name resolved from the Slot's schedule reference. Used by scheduling surfaces to show provider availability without joining against the raw Schedule resource.

### 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_id`, `event_type`, `source`, `source_system`, `confidence`, `effective_at`, `created_at`), 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)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.amigo.ai/developer-guide/platform-api/platform-api/fhir.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.