The master patient index: who the patient is, under every identifier, and where their records are.

Documentation · Quick start · What ships today · Licensing

Project

Quality and security

Conformance

What FerroPIX does

Every hospital, clinic and laboratory gives the same person its own patient number. When records have to come together, for a referral, a shared care plan or a regional record, someone has to know that these numbers belong to one person. Getting that wrong means a record in the wrong file, or a record that is never found.

FerroPIX keeps that knowledge. It holds the cross-reference between the identifiers each organisation uses, finds a patient from their name and date of birth, and flags likely duplicates for a person to review. Other systems ask it over the IHE profiles hospital integrators already use: PIX (which identifiers belong together) and PDQ (find a patient by their details), in their modern FHIR forms PIXm and PDQm and over HL7 v2 messages.

It keeps identifying data in one place, outside the clinical record, which is where the openEHR platform model puts the patient index.

Who it is for

• Hospitals and care networks that need one reliable view of who a patient is across their own systems and their partners'.
• Integrators and regional exchanges that link records between organisations and need a patient index that speaks the IHE profiles.
• Data stewards who review and resolve possible duplicate patients in the operator console.

Why you can trust what it claims

Every release is signed and comes with a software bill of materials (the list of every component inside) and SLSA build provenance, so you can check that what you install is what was built here. The source is public, and every feature is in this repository: there is no paid edition with extra functions. Each conformance badge above links to its pass list, every example the IHE PIXm, PDQm and PMIR guides publish, with the reason for any that fails, so you can check a result against the standard yourself.

Part of FerroHEALTH

FerroPIX is one of five FerroHEALTH servers. Each does one job and reaches the others only over published standards: FerroEHR stores the record, FerroBRIDGE translates it to FHIR and the OMOP research model, FerroFED connects records across organisations and borders, FerroPIX matches patient identities, and FerroTERM serves the code systems (the shared lists of medical terms). Any system that speaks PIXm, PDQm or HL7 v2 can use FerroPIX, not only the FerroHEALTH ones. Sign-in, the audit trail and the web consoles come from three shared libraries: FerroAUTH, FerroAUDIT and FerroUI.

Quick start

The quickstart runs the published image beside PostgreSQL and a development sign-in server. You need Docker Compose, git, openssl and jq:

git clone https://github.com/FerroHEALTH/FerroPIX && cd FerroPIX
mkdir -p secrets && umask 077
openssl rand -base64 32 > secrets/ferropix-data-key
openssl rand -hex 16 > secrets/postgres-password
openssl rand -hex 16 > secrets/ferropix-db-password
printf 'postgresql://ferropix:%s@postgres:5432/ferropix' \
  "$(cat secrets/ferropix-db-password)" > secrets/ferropix-db-url
docker compose up --wait
curl http://localhost:8080/health/readiness

Then ask for a patient's other identifiers (ITI-83) with a development token. The store starts empty, so the answer says the identifier is not known yet:

token="$(curl -s -d grant_type=client_credentials \
  -d client_id=quickstart-source -d client_secret=any \
  -d scope=system/Patient.rs http://localhost:8180/ferropix/token | jq -r .access_token)"
curl -H "Authorization: Bearer $token" \
  'http://localhost:8080/fhir/Patient/$ihe-pix?sourceIdentifier=urn:oid:2.999.1.1|1'

The PIXm Manager shows how to feed a patient first, and Deployment covers the image, the Helm chart and production settings.

What ships today

Patient identity

• The PIXm Manager: the identifier cross-reference query (ITI-83) and the FHIR identity feed (ITI-104)
• The PDQm Supplier: find a patient by their details (ITI-78) and match (ITI-119)
• The HL7 v2 face: the PIX feed and query and the PDQ query over MLLP (ITI-8, ITI-9, ITI-21)
• Matching: a probabilistic score for every possible duplicate, with a review queue

Security and audit

• Who may call the server: SMART access tokens from the issuers you trust
• The audit trail of every IHE transaction, in the IHE BALP format

Operations

• The operator console: search, the patient record, the review queue, merge and unmerge
• The operator API the console reads
• Container images and release binaries for amd64 and arm64, signed, and a Helm chart

Libraries

• ihe-iti, the IHE identity profiles, and nl-generic-functions, the Dutch Generic Functions, as Rust crates

Published crates (2)

Crate	What it does	Version	Docs	Downloads
ihe-iti	The IHE identity profiles PIXm, PDQm, mCSD, PMIR and XCPD, one feature per profile, with their audit records
nl-generic-functions	The Dutch Generic Functions: localization (NVI), consent (Mitz), addressing (LRZa) and authentication (Nuts)

Learn more

• Documentation and the FerroHEALTH book
• What FerroPIX is, with what is built and what is planned, and conformance and specification pins
• Changelog and milestones
• Security policy
• Contributing, code of conduct, support, governance and maintainers

Licence

Business Source License 1.1 (LICENSE), with Apache License 2.0 as the Change License four years after each version; the licensing page says when you need a commercial licence from Cadasto B.V.