Patient linking

#Overview

A person's medical records are spread across health insurers, medical systems of record, and national exchanges. Each source records patient demographics differently — names, addresses, identifiers, and even birth dates can vary.

Flexpa preserves these source-specific representations as separate FHIR Patient resources rather than merging them into a single lossy record.

This creates a practical problem: how do you query across all of a person's data when it's split across multiple Patient resources? The answer depends on the consent flow type.

Identity-verified search (IAL2) — the patient verifies their identity once (via CLEAR, ID.me, or Persona), and multiple sources are discovered through TEFCA under a single Consent. Flexpa creates an identity-verified master Patient and links each source Patient back to it.
Self-attested search (IAL1) — the patient self-attests their demographics (first name, last name, date of birth) and selects one or more sources by searching the endpoint directory. Multiple sources connected in the same session are grouped under a single Consent. Flexpa creates a self-attested master Patient and links each source Patient back to it.

For both IAL2 and IAL1 search, Flexpa provides aggregated operations — $everything and $summary — that follow Patient.link entries automatically, returning a unified view from a single API call.

#Why multiple patients?

Flexpa preserves source representations of medical records rather than merging them into a single lossy record. Sources diverge for many reasons:

Name variations — one system records "Jane", another "Jane A.", another "Jane Anne Smith"
Address changes — people move, and older records retain previous addresses
Identifier differences — each payer and provider assigns their own MRNs and member IDs, often critical for downstream analysis
Demographic gaps — some sources capture gender or race, others don't

Your application should expect and prepare for multiple Patient resources per individual.

Overview: a person connects to multiple sources via Standard OAuth or IAL2 verification, producing linked Patient resources queryable through $PATIENT_ID.

One person, three Patient resources

[
  {
    "resourceType": "Patient",
    "id": "ial2-master",
    "meta": {
      "security": [{
        "system": "https://smarthealth.cards/ial",
        "code": "IAL2"
      }]
    },
    "name": [{ "family": "Smith", "given": ["Jane", "Anne"] }],
    "gender": "female"
  },
  {
    "resourceType": "Patient",
    "id": "humana-789",
    "name": [{ "family": "Smith", "given": ["Jane"] }],
    "address": [{ "state": "TX" }]
  },
  {
    "resourceType": "Patient",
    "id": "mayo-012",
    "name": [{ "family": "Smith", "given": ["Jane", "A"] }],
    "address": [{ "state": "MN", "city": "Rochester" }]
  }
]

#Data model

#Consents

A Consent represents one completed OAuth authorization through Flexpa Consent. When a patient connects to two different providers through separate consent flows, your application receives two distinct Consents.

#Access tokens

A Patient Access Token is scoped to exactly one Consent. One token gives you access to all Patient Authorizations within that Consent.

Identity-verified or self-attested search — multiple sources are grouped under a single Consent with one access token that covers all discovered or selected sources.
Standard OAuth — each source is a separate Consent with its own access token. Two payers = two tokens.

#Patient Authorizations

Each Consent contains one or more Patient Authorizations, each representing a connection to a specific endpoint (payer, provider, or QHIN source). For standard OAuth, a Consent has a single Patient Authorization. For IAL2 flows, QHIN network queries can discover multiple sources — all grouped under a single Consent. For IAL1 search flows, the patient self-attests demographics and selects one or more endpoints from the endpoint directory — each selection becomes a Patient Authorization under the same Consent, alongside an IAL1 Patient Authorization that anchors the self-attested master Patient.

Entity diagram showing Consent, Access Token, Patient Authorization, Endpoint, and Patient relationships.

#How it works

For IAL2 and IAL1 search flows where multiple sources are grouped under a single Consent, Flexpa automatically creates bidirectional FHIR Patient.link entries between Patient resources after each data sync completes.

Two link types are used:

refer — added to each source Patient, pointing to the master Patient. Signals that this record defers to the master for identity resolution.
seealso — added to the master Patient, pointing to each source Patient. Signals that additional data exists at the referenced source.

The master Patient acts as the identity anchor for the Consent. Source-specific Patients retain their original demographics as received from each payer or provider. When both IAL2 and IAL1 master candidates exist on the same Consent, Flexpa prefers the IAL2 master.

When the same patient verifies their identity through IAL2 again under a new Consent, Flexpa reuses the same master Patient resource. Both Consents' Patient Authorizations remain queryable through their respective access tokens; only the most recent Consent's IAL2 authorization drives upstream refresh and TEFCA sync.

#Identity assurance

The master Patient carries a meta.security label indicating its identity assurance level using the SMART Health Cards identity assurance code system. This follows NIST SP 800-63A identity assurance levels and lets your application programmatically distinguish verified, self-attested, and source-specific patients.

IAL2 — identity verified through CLEAR, ID.me, or Persona during a TEFCA search.
IAL1 — self-attested name and birth date from the search flow's demographics step.

Source-specific Patients carry no identity assurance label.

#Resource tagging

Every FHIR resource Flexpa returns is tagged with the Consent and Patient Authorization from which it came. These tags appear in the resource's meta.tag array and let you trace data provenance back to specific sources. See Tags for the full list of tag systems.

Bidirectional linking between IAL2 master Patient and source-specific Patients using refer and seealso link types.

#Aggregated operations

In a standard FHIR server, Patient/$everything and Patient/$summary are scoped to a single Patient resource. Flexpa extends this behavior for linked patients — when you use $PATIENT_ID with either operation, Flexpa automatically follows seealso links and aggregates data from all linked source patients into a single response.

Calling $everything or $summary with a specific Patient ID still returns data scoped to only that Patient.

#The $PATIENT_ID wildcard

$PATIENT_ID is a special wildcard that is replaced inline in the request URL with the consent-scoped destination Patient ID — the destinationPatientId of the first Patient Authorization on the access token's Consent. For IAL2 and IAL1 search Consents this is the master Patient ID; for standard OAuth Consents it is the single source Patient ID. The wildcard itself only swaps in this one ID; any inclusion of additional linked source Patients happens downstream during aggregated operations (for example, $everything and $summary) that follow Patient.link seealso references after the URL has been resolved. See Wildcard Parameters for more details.

#$everything

Aggregates raw FHIR resources from all linked patients into a single searchset Bundle:

Flexpa resolves $PATIENT_ID to the master Patient (IAL2-verified or IAL1 self-attested)
The master's seealso links are followed to discover all source Patients
$everything is fetched for each source Patient in parallel
Results are deduplicated — if the same resource appears from multiple sources, only the first occurrence is kept
A single searchset Bundle is returned with access control tags preserved on every resource

See Patient/$everything for full operation details.

#$summary

Follows the same aggregation as $everything, then generates an International Patient Summary (IPS) Bundle from the merged data. The IPS is a standardized clinical document containing allergies, medications, conditions, immunizations, and other key clinical data — structured for cross-border and cross-system portability.

See Patient/$summary for full operation details.

$everything

Aggregation flow: resolve $PATIENT_ID, find seealso links, fetch linked patient data, deduplicate and merge into one searchset Bundle.

$summary

#Next steps

FHIR Records

Complete reference for retrieving and working with FHIR resources through Flexpa's API

View Records Documentation →