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 whether the Consent includes identity verification.

With identity verification — the patient verifies their identity once (via CLEAR or ID.me), and multiple sources are discovered under a single Consent. Flexpa links the resulting Patient resources together and provides aggregated operations — $everything and $summary — that follow those links automatically, returning a unified view from a single API call.
Without identity verification — each source connection produces its own Consent and access token. Your application queries data from each Consent independently.

#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",
    "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.

With identity verification — multiple sources are grouped under a single Consent with one access token that covers all discovered sources.
Without identity verification — 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 typically has a single Patient Authorization. For IAL2 flows, QHIN network queries can discover multiple sources — all grouped under a single Consent.

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

#How it works

For IAL2 flows where multiple sources are discovered 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 IAL2 Patient. Signals that this record defers to the identity-verified master for identity resolution.
seealso — added to the IAL2 Patient, pointing to each source Patient. Signals that additional data exists at the referenced source.

The IAL2 Patient acts as the authoritative identity anchor. Source-specific Patients retain their original demographics as received from each payer or provider.

#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 resolves to all Patient resources accessible under the current access token. For IAL2 Consents with linked patients, this means the IAL2 master and all source patients. For standard OAuth Consents, $PATIENT_ID resolves to the single Patient resource associated with that authorization. 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 IAL2 master Patient
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 →