Case Study: The Patient-Matching Parameter Trap

I have worked on patient-matching APIs from both sides of the table. I supported one as a vendor and later consumed similar APIs in integration workflows.

One lesson survived both roles: a match score is only useful when its contract is explicit.

This case study covers an endpoint whose threshold and ranking parameters did not compose as the documentation implied. The implementation was internally consistent. The public contract was not.

I have generalized the vendor, endpoint, parameter names, and example values. No customer details, patient data, or private implementation details appear here. The parameter interaction and operational lessons are unchanged.

TL;DR

• A threshold parameter looked like a hard filter. A “best matches” mode could bypass it.
• The failure was an undocumented precedence rule, not proof that the underlying matching algorithm was wrong.
• Match scores are model-specific rankings, not portable probabilities.
• Consumers should verify returned candidates, test parameter combinations, and keep uncertain matches out of automatic workflows.
• API owners should reject ambiguous combinations or publish a truth table and machine-readable strategy metadata.

The contract I thought I had

The anonymized request looked roughly like this:

GET /v1/{tenantId}/patients/matches?minScore=20&bestOnly=true

The documentation described each option separately:

• minScore set the lowest acceptable score.
• bestOnly returned a small ranked set above a built-in floor.

Read independently, both statements sounded reasonable. Read together, they left the important question unanswered: which threshold wins?

These were all plausible contracts:

Request	Plausible rule	Lowest returned score
minScore=20	Apply the caller's threshold	20
bestOnly=true	Use the mode's built-in floor	16
Both	Filter at 20, then rank	20
Both	Enter best-only mode and ignore minScore	16

We observed the last behavior. Candidates below the requested threshold could appear when the mode flag was present.

That result did not prove the matcher was defective. It proved the client and server did not share the same contract.

Why the ambiguity mattered

ONC defines patient matching as linking a person's data within and across systems. It depends on multiple demographic fields, including name, birth date, phone number, and address.

The operational tradeoff is unavoidable. Raising a threshold may reduce false-positive matches while increasing false negatives. Lowering it can do the reverse. A threshold therefore encodes a risk decision, not just a query preference.

If another parameter silently changes that decision, downstream code may:

• attach work to the wrong record;
• create duplicates after rejecting valid candidates;
• send borderline candidates into an automatic path; or
• force staff to resolve avoidable exceptions manually.

The score itself needs careful language too. A score of 20 is not automatically “20 percent confidence.” It may be a vendor-specific weighted rank. Unless the API defines calibration, scale, and model version, consumers should not treat it as a probability.

Where the documentation failed

The docs explained parameters as a list. The endpoint behaved as a state machine.

The missing contract covered four things:

1. Classification: Is each parameter a filter, ranking input, result cap, or mode switch?
2. Order: Does filtering happen before or after ranking?
3. Conflict behavior: Are combinations composed, rejected, or resolved by precedence?
4. Versioning: Can a scoring-model change alter the meaning of an existing threshold?

This distinction also matters in standards-based APIs. FHIR R4 search allows servers to support subsets of search behavior. It also defines strict and lenient handling for unsupported parameters. A server's discoverable capabilities help, but custom matching semantics still need endpoint-specific rules.

What I do as a consumer

1. Separate retrieval from the match decision

I treat the upstream result as a candidate set. A local decision layer determines whether to link, review, or reject.

That layer should use an approved set of demographics and a documented policy. It should not quietly invent a second opaque score.

API candidates -> local validation -> link | manual review | no match

For identity-critical actions, uncertainty belongs in a review queue. A “best” candidate is not necessarily a safe candidate.

2. Test combinations, not individual parameters

I build a small synthetic fixture set around the contract:

• exact demographic match;
• one-field variation;
• two plausible candidates;
• no candidate above the requested threshold;
• minScore alone, mode alone, and both together; and
• an unsupported or malformed parameter.

The assertions cover candidate count, score bounds, ordering, warnings, and decision state. Synthetic data keeps protected health information out of test fixtures.

3. Log decisions without logging identity data

Useful telemetry includes:

• endpoint and contract version;
• which request options were enabled;
• candidate count and score band;
• local decision (link, review, or no_match); and
• a correlation ID for the transaction.

Names, dates of birth, addresses, and raw payloads do not belong in routine diagnostic logs. If a restricted audit workflow needs them, that storage needs its own access and retention controls.

4. Pin the safe behavior

When I find an interaction like this, I add a regression test before changing the integration. I also record the observed server version and request shape.

That turns “support told us this once” into evidence the team can rerun.

What I would ship as the API owner

The fastest documentation fix is a parameter matrix:

minScore	bestOnly	Server behavior
omitted	false	Default candidate retrieval
set	false	Exclude candidates below minScore
omitted	true	Rank and cap using the mode's documented floor
set	true	Reject as conflicting, or apply one documented rule

The product fix is to remove silent ambiguity:

• reject incompatible options with a clear 4xx response;
• return the strategy and filters actually applied;
• version the score model or scoring contract;
• publish synthetic request-and-response fixtures; and
• run those fixtures as contract tests in continuous integration.

A response envelope could expose the decision without revealing proprietary scoring logic:

{
  "strategy": "best-candidates-v3",
  "filtersApplied": ["minScore:20"],
  "candidateLimit": 5,
  "warnings": []
}

OpenAPI can describe names and types. It cannot, by itself, make cross-parameter precedence obvious. That rule still needs machine-readable constraints, examples, and plain language.

The larger lesson

Patient matching is already difficult because source demographics and local policies vary. An ambiguous API should not add another hidden variable.

The durable pattern is simple:

• make retrieval and decision-making separate steps;
• state which options are filters and which change modes;
• test combinations with synthetic records;
• expose the strategy the server applied; and
• route uncertain identity decisions to people.

The strongest integration code is rarely the cleverest. It is the code that makes risk visible, behavior repeatable, and surprises testable.

Further reading

• ONC: Patient Identity and Patient Record Matching
• ONC Patient Demographic Data Quality Framework
• FHIR R4 Search
• Operationalizing Healthcare API Integrations