Implement FHIR patient matching using the $match operation to find the best matching Patient record in a server when integrating data from an external system
domain: hl7.org/fhir · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
POST a Parameters resource to [base]/Patient/$match containing a resource parameter with a Patient resource populated with known identifiers, demographics, and contact information
Include the onlyCertainMatches parameter set to false to receive candidate matches with confidence scores, or set to true to return only high-confidence definite matches
Evaluate the returned Bundle entries, each containing a Patient resource and a search.score between 0 and 1 indicating match confidence, along with an extension for match grade (certain, probable, possible)
Implement a matching threshold policy: treat certain and high-score probable matches as auto-linkable, queue possible matches for manual review, and create new records only when no candidates exceed the threshold
Log all $match requests and outcomes for audit purposes, including the input demographics, candidate IDs returned, scores, and the final linking decision
Known gotchas
The $match algorithm is server-defined and not standardized; confidence scores from different servers are not comparable and the same patient may get different scores on different systems
Patient records with sparse demographics (missing date of birth or address) produce many low-confidence candidates; requiring at least one strong identifier (MRN, SSN last 4) significantly improves match quality
Linking on a probable match without manual review creates a patient safety risk; always route ambiguous matches to a human workflow before merging records in downstream systems
Give your agent this knowledge — and 15,600+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?