> For the complete documentation index, see [llms.txt](https://docs.oomus.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.oomus.org/integrations/fhir-r4.md).

# HL7 FHIR R4

Oomus CampaignID supports the standard **HL7 FHIR R4** (Fast Healthcare Interoperability Resources, Release 4) for the exchange of health identity information with other digital health systems.

***

## FHIR Endpoint

```
https://api.oomus.health/fhir/r4/
```

The Oomus CampaignID FHIR R4 endpoint exposes MPI identities as standardized FHIR resources, enabling interoperability with any FHIR R4-compatible system.

***

## What is supported

### FHIR Resources

| Resource     | Support      | Description                               |
| ------------ | ------------ | ----------------------------------------- |
| `Patient`    | Read + Write | Beneficiary identity (MPI)                |
| `Identifier` | Read         | Cross-system identifiers (MPI, DHIS2 UID) |

### FHIR Operations

| Operation  | Method | Endpoint                          | Description                         |
| ---------- | ------ | --------------------------------- | ----------------------------------- |
| Read       | `GET`  | `/fhir/r4/Patient/{mpi_id}`       | Get a patient by MPI ID             |
| Search     | `GET`  | `/fhir/r4/Patient?identifier=...` | Search by identifier                |
| Creation   | `POST` | `/fhir/r4/Patient`                | Create a new patient (→ MPI)        |
| PIXm Query | `GET`  | `/fhir/r4/$cross-reference`       | Cross-reference identity resolution |

### PIXm queries (Patient Identity Cross-Reference for Mobile)

The **PIXm** (IHE IT Infrastructure) makes it possible to find all known identifiers for the same patient in different systems:

```bash
GET /fhir/r4/$cross-reference?sourceIdentifier=dhis2|abcDEF123gh&targetSystem=oomus-mpi
```

**Response:**

```json
{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "targetIdentifier",
      "valueIdentifier": {
        "system": "https://oomus.health/mpi",
        "value": "SN-DKR-26-9XQ7LM2A"
      }
    }
  ]
}
```

***

## FHIR R4 Patient Resource — Example

Here is an example of a resource `Patient` FHIR R4 exposed by the Oomus endpoint:

```json
{
  "resourceType": "Patient",
  "id": "SN-DKR-26-9XQ7LM2A",
  "meta": {
    "profile": [
      "http://hl7.org/fhir/StructureDefinition/Patient"
    ],
    "lastUpdated": "2026-05-15T09:00:00Z"
  },
  "identifier": [
    {
      "system": "https://oomus.health/mpi",
      "value": "SN-DKR-26-9XQ7LM2A",
      "type": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
            "code": "MR",
            "display": "Medical Record Number"
          }
        ]
      }
    },
    {
      "system": "https://dhis2.sante.gov.sn",
      "value": "abcDEF123gh",
      "type": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
            "code": "EI",
            "display": "Employee Number"
          }
        ]
      }
    }
  ],
  "name": [
    {
      "use": "official",
      "family": "Diallo",
      "given": ["Aminata"]
    }
  ],
  "gender": "female",
  "birthDate": "1995-03-15",
  "address": [
    {
      "district": "Dakar",
      "country": "SN"
    }
  ],
  "telecom": [
    {
      "system": "phone",
      "value": "+221771234567",
      "use": "mobile"
    }
  ]
}
```

***

## Compatible systems

The Oomus CampaignID FHIR R4 endpoint is compatible with the following systems:

| System                              | Type                           | Use case                                    |
| ----------------------------------- | ------------------------------ | ------------------------------------------- |
| **OpenHIE**                         | Health exchange infrastructure | Client Registry / national MPI access point |
| **HAPI FHIR**                       | Open source FHIR server        | Integration with an existing FHIR server    |
| **Google Cloud Healthcare FHIR R4** | Cloud FHIR                     | Exchange with Google Cloud systems          |
| **Azure Health Data Services**      | Cloud FHIR                     | Azure integration                           |
| **OpenMRS**                         | Clinical information system    | Patient identity sharing                    |
| **iHRIS**                           | Health HR                      | Patient-health worker identity linking      |

***

## Use case

### Cross-program identity resolution

A beneficiary enrolls in a vaccination program, then in a nutrition program. Thanks to FHIR PIXm:

1. The nutrition program queries the Oomus MPI: "Does this patient already exist?"
2. The MPI responds with the existing MPI identifier (`SN-DKR-26-9XQ7LM2A`)
3. Both programs share the same sovereign identity
4. All generated cards carry the same MPI identifier

### National health information exchange

As part of a **National Health Information System (SNIS)** :

1. Oomus CampaignID publishes MPI identities on the FHIR R4 endpoint
2. The national OpenHIE infrastructure consumes this data
3. Other systems (laboratory, pharmacy, hospital) can resolve a patient's identity via PIXm
4. The longitudinal patient view is maintained across all points of care

### Integration with an existing patient registry

If your organization already has a FHIR patient registry (HAPI FHIR, Google FHIR):

1. Configure bidirectional synchronization from the Oomus settings
2. New MPIs created in Oomus are automatically published to your FHIR registry
3. Updates from the external registry can trigger an update to the Oomus MPI

***

## FHIR endpoint authentication

The FHIR R4 endpoint uses the same JWT authentication system as Oomus CampaignID:

```bash
# Authenticated FHIR request
curl -X GET "https://api.oomus.health/fhir/r4/Patient/SN-DKR-26-9XQ7LM2A" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \\
  -H "Accept: application/fhir+json"
```

For machine-to-machine (M2M) systems, a **Client Credentials OAuth2 flow** is available — contact Oomus support for configuration.

***

## Current limitations

| Feature                 | Status                  |
| ----------------------- | ----------------------- |
| Resource `Patient`      | Supported               |
| Resource `Observation`  | Not supported (roadmap) |
| Resource `Immunization` | Not supported (roadmap) |
| Resource `Encounter`    | Not supported           |
| FHIR Subscriptions      | Not supported           |
| FHIR Bundles            | Supported (read only)   |

***

## Next steps

* [MPI sovereign identity](/features/mpi-sovereign-identity.md)
* [MPI API Reference](/api-reference/mpi.md)
* [Data Protection](/security/data-protection.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.oomus.org/integrations/fhir-r4.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.