> 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/features/mpi-sovereign-identity.md). # MPI Sovereign Identity The **sovereign Master Patient Index (MPI)** is one of the most distinctive features of Oomus CampaignID. It guarantees every citizen a unique, durable, and interoperable digital health identity across all health programs. *** ## What is the sovereign MPI? The MPI addresses a fundamental problem in fragmented health systems: **the same individual may be registered under different identities in different programs** — with varied name spellings, imprecise dates of birth, and unrelated local identifiers. ### Fundamental principle > **1 citizen = 1 sovereign digital health identifier** This identifier is: * **Cross-program** : shared across vaccination, nutrition, HIV, health insurance, etc. * **Lifelong** : created at the first interaction and retained indefinitely * **Sovereign** : hosted on the national (or organizational) infrastructure, without dependence on a third party * **Interoperable** : HL7 FHIR R4, DHIS2 Tracker, OpenHIE compatible *** ## MPI identifier format An Oomus MPI identifier follows the format: ``` SN-DKR-26-9XQ7LM2A ``` Breakdown of each segment: | Segment | Example | Description | | ------------------- | ---------- | -------------------------------------------------------------------------------------------- | | **Country** | `SN` | Country ISO 3166-1 alpha-2 code | | **Region/District** | `DKR` | Health region or district code (3 letters) | | **Year** | `26` | The last 2 digits of the registration year | | **Unique code** | `9XQ7LM2A` | Cryptographically secure random Base36 identifier (8 characters, \~2.8 billion combinations) | The unique code is generated by a **CSPRNG (Cryptographically Secure Pseudo-Random Number Generator)**, ensuring no collision and unpredictability. *** ## Probabilistic deduplication engine When a new beneficiary is registered (via the API or via DHIS2), the MPI engine checks whether they already exist in the registry before creating a new identifier. ### Scoring algorithm The engine computes a **composite similarity score** based on several attributes: | Attribute | Algorithm | Weight | | ------------------- | ------------------------------------ | ------ | | First name | Jaro-Winkler + African normalization | 25% | | Last name | Jaro-Winkler + African normalization | 25% | | Date of birth | Exact match / ±1 year | 20% | | Sex | Exact match | 10% | | Commune / District | Administrative match | 10% | | External identifier | DHIS2 UID / other ID match | 10% | ### African name normalization The engine includes a specialized normalization layer for West African names: * Handling spelling variants (Ibrahima / Ibrahim / Brahim) * Diacritic folding (é → e, ñ → n, ñ → n) * Frequent first/last name inversion in some regions * Recognition of compound names (Mamadou Lamine / Lamine Mamadou) * Wolof/Pulaar/Manding transliteration ### Decision thresholds | Score | Decision | Action | | ----------- | -------------- | ----------------------------------------------- | | ≥ 0.95 | Certain match | Automatic link to the existing identity | | 0.75 – 0.94 | Probable match | Marked for manual review (Duplicates interface) | | 0.50 – 0.74 | Possible match | Alert in the dashboard | | < 0.50 | No match | New identity created | *** ## QR token — Privacy preservation The QR code printed on the card never contains **never** the MPI identifier in clear text. ### Why this choice? If the MPI identifier were directly encoded in the QR, anyone with a generic QR reader could read a beneficiary's health identity simply by scanning their card — a serious privacy violation. ### How it works Instead, the QR code contains an **opaque token** : * Derived from the MPI identifier + campaign code + a server secret via SHA-256 * Non-reversible: it is impossible to recover the MPI from the token alone * Verifiable: the Oomus server can confirm a token's validity without exposing the MPI * Offline-verifiable: the `registry.json` registry allows verification without a connection ``` QR token = SHA-256(mpi_id + campaign_prefix + server_secret) ``` > This mechanism ensures that a field agent can verify only one piece of information: "this card is valid for this campaign". They learn nothing else about the beneficiary. *** ## MPI identifier on cards For the 10 DHIS2 card templates (vital / emerald / pulse / mothercare / shield / nomad / aero / horizon / aurora / sovereign), the sovereign MPI identifier is displayed in the **card footer**, replacing the traditional barcode. The `sovereign` template displays the MPI-ID prominently in large bold text in the identity area (boarding-pass design 1011×375 px @ 300 DPI), accompanied by a fingerprint icon (8 ridges). The function `generate_dhis2_card_png()` accepts an optional parameter `sovereign_config: Optional[SovereignCardConfig]` to customize the accent/background colors, font scale, and maximum number of displayed attributes. **Advantages over the barcode:** * Readable by the health worker (human format) * Usable for manual search in the registry * More robust to physical degradation of the card * Carries semantic information (country, region, year) *** ## KYC verification flow The KYC (Know Your Beneficiary) flow allows a beneficiary's identity to be verified and enriched: ``` 1. The health worker scans the card (QR or manual MPI entry) 2. Query the verification portal (online or offline) 3. Validate the cryptographic QR token 4. Display status: valid / invalid / revoked 5. [If online] Display the number of associated programs (without PII) ``` *** ## DHIS2 → MPI resolution flow During DHIS2 synchronization, each enrollment is processed according to the following flow: ``` DHIS2 Enrollment │ ▼ Extract attributes (first name, last name, DOB, sex, etc.) │ ▼ Name normalization (African algorithm) │ ▼ Calculate similarity score (probabilistic engine) │ ├─ Score ≥ 0.95 → Link to existing MPI │ ├─ Score 0.75–0.94 → Manual review queue │ └─ Score < 0.75 → Create new MPI identifier │ ▼ Generate Base36 code (CSPRNG) Format: {COUNTRY}-{REGION}-{YEAR}-{8 chars} ``` *** ## HL7 FHIR R4 interoperability The Oomus MPI is compatible with international interoperability standards: * **FHIR R4 Patient resource** : each MPI entry can be exposed as a Patient resource * **PIXm queries** (Patient Identity Cross-Reference for Mobile): cross-program identity resolution via FHIR queries * **FHIR endpoint** : `https://api.oomus.health/fhir/r4/` See [HL7 FHIR R4 Integration](/integrations/fhir-r4.md) for full documentation. *** ## Public MPI API endpoints | Method | Endpoint | Description | | ------- | -------------------------------- | --------------------------------------- | | `POST` | `/mpi/register` | Register a new beneficiary | | `GET` | `/mpi/search` | Search the MPI registry | | `GET` | `/mpi/{mpi_id}` | Get the details of an MPI identity | | `PATCH` | `/mpi/{mpi_id}` | Update an MPI identity | | `POST` | `/mpi/match` | Check a match (score) | | `POST` | `/mpi/{mpi_id}/link-dhis2` | Link a DHIS2 UID to an MPI | | `GET` | `/mpi/resolve-dhis2/{dhis2_uid}` | Resolve a DHIS2 UID to an MPI | | `POST` | `/mpi/merge` | Merge two duplicate identities | | `GET` | `/mpi/{mpi_id}/card` | Get the associated card | | `GET` | `/mpi/verify/{token}` | Verify a QR token **(public, no auth)** | | `GET` | `/mpi/qr-config` | Active QR configuration | See [API reference — MPI](/api-reference/mpi.md) for full details with examples. *** ## MPI user interface The Oomus CampaignID interface includes three pages dedicated to the MPI: ### MPI Dashboard Overview of registry statistics: total number of identities, deduplication rate, geographic distribution, time trend. ### MPI Registry Paginated and filterable table of all identities in the registry. Search by name, MPI ID, district, associated program. Access details for each identity. ### Duplicate review Dedicated interface for manual review of probable matches (score 0.75–0.94). The agent can: * View the two identities side by side * See the similarity score and the contributing fields * Validate the merge or reject the match * Add a decision note (audited) *** ## Next steps * [API reference — MPI](/api-reference/mpi.md) * [DHIS2 integration](/features/dhis2-integration.md) — MPI resolution during synchronization * [HL7 FHIR R4](/integrations/fhir-r4.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/features/mpi-sovereign-identity.md?ask=&goal= ``` `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.