FHIR API Reference

The Flexpa API is based on the HL7® FHIR® standard that gives you access to health insurance claims, plan details, and medical records from our network of payers.

Every resource available conforms to the FHIR R4 standard.

#How it works

1. Patients consent to transfer health data through Flexpa Consent to your application
2. Your server exchanges the consent for an access token
3. Use these tokens to make authenticated requests to Flexpa's FHIR API endpoints
4. Receive standardized FHIR-compliant health data that you can use in your application

#What you need

To use the Flexpa API effectively, you'll need:

• A pair of API Keys (talk to our team)
• A backend server to securely manage tokens and make API requests
• Understanding of FHIR resources (recommended)

You can use the API in test mode to explore endpoints with sample data before going live with real patient data.

The Flexpa API uses a two-layer authentication system. API Keys are used for securely identifying your application to Flexpa and for OAuth token requests.

API Keys come in pairs: a Publishable Key and a Secret Key.

Publishable keys have the prefix pk_test_ for test mode and pk_live_ for live mode. They are used in client-side code, like in the Consent authorization step.

Secret keys have the prefix sk_test_ and sk_live_. They are used only in server-side code and must be kept secure.

#Access Tokens

The Flexpa API supports two distinct types of access tokens, each designed for different use cases. Access tokens are JWTs that contain claims about the token's identity and permissions.

Both are sent to the API in an Authorization: Bearer header.

#Differences

Patient Authorizations are the secure permissions granted by patients to access their health data. These authorizations are what enable the creation of Patient Access Tokens.

A Patient Authorization represents consent from a patient to access their data from a specific health plan or provider. When a patient completes the Consent flow:

1. They select their health plan or provider
2. They authenticate with that organization
3. They explicitly consent to share specific data with your application
4. Flexpa creates a Patient Authorization that maintains this consent

Patient Authorizations can be configured as either:

• ONE_TIME: A single 24-hour window of access after which the authorization and all associated data are deleted
• MULTIPLE: Ongoing access that refreshes regularly without requiring the patient to re-authorize

Each Patient Authorization has a unique lifecycle with different states which you can track via the introspect endpoint. When a patient chooses to revoke access, you can use the revoke endpoint to delete the authorization and associated data.

When a patient authorizes access to their health data through Flexpa Consent, a synchronization process is initiated to retrieve and cache their records from the health plan's API. This process is managed through a Sync Job, which allows you to track the status of data retrieval.

Sync Jobs are automatically created after a successful patient authorization and progress through several states as data is retrieved, processed, and made available through the Flexpa API.

All FHIR API requests must be made with a Patient Access Token or an Application Access Token in the Authorization header.

FHIR API routes begin with the /fhir/ subpath of the URL. Flexpa's FHIR API is designed to provide a consistent, reliable, and developer-friendly experience when working with health data. Our architecture offers several key benefits:

• Consistent API Experience: We normalize the behavior of FHIR operations across all payers, providing uniform support for features like Patient $everything.

• Enhanced Search Capabilities: Flexpa supports comprehensive search functionality, including consistent implementation of parameters like patient and powerful features like _include across all data sources.

• Standardized Data Model: We dynamically adapt to the unique implementations of each payer's FHIR API and transform the data to provide a consistent experience, including:

  • Creating MedicationRequest resources from pharmacy claim data in ExplanationOfBenefit resources (learn more)
  • Generating US Core clinical resources (Encounter, Condition, Procedure) from claims data (learn more)
  • Generating InsurancePlan resources for supported Medicare Advantage Part C Coverage from CMS PBP reference data (learn more)
  • Normalizing code systems and adding human-readable display values
  • Enhancing resource references for better data connectivity
  • Filling in missing information where available from other sources

Explore these powerful features to enhance your development experience:

• Wildcard Parameters
• Search Result Parameters
• Pagination
• Referenced Resources
• Code Systems
• Errors

A read is the most basic operation in FHIR. It allows you to retrieve the current version of a single resource by its ID.

For a full list of available Resources, please refer to the FHIR Resources documentation.

Searches on Flexpa API follow the RESTful style of the FHIR specification by submitting a GET HTTP request to the base URL of the resource with parameters to define the exact search criteria to filter the response.

Unique to the Patient resource, the Patient $everything returns all patient-compartmentalized resources, as well as any Organization, Location, Practitioner, and Medication resources that are present in the patient's FHIR data.

You will need to make additional search requests for any non-patient compartmentalized resources, for example:

• Location
• Device
• PractitionerRole

The $summary operation generates an International Patient Summary (IPS) document for the patient. The IPS is a standards-based clinical summary designed for unscheduled or cross-border care, returning a FHIR Bundle of type document with a Composition resource that organizes the patient's key health information into 14 standardized sections.

The generated IPS document includes:

• PDF rendering — a DocumentReference containing a rendered PDF of the patient summary is automatically included in the Bundle, suitable for display in systems that do not support FHIR
• Status-based filtering — only clinically relevant resources (e.g., active medications, completed immunizations, final lab results)
• Section narratives — each section contains a human-readable XHTML table
• Empty section handling — sections with no data include emptyReason of unavailable; sections excluded via _section include emptyReason of withheld
• Confidentiality tagging — the Bundle carries a meta.security high water mark reflecting the most restrictive confidentiality code across included resources

Use the _section query parameter to restrict which IPS sections appear in the summary. This is useful when patients want to share only specific categories of health data — for example, sharing allergies and medications with a new provider but withholding social history. Values can be LOINC section codes or short aliases. When _section is omitted, all available sections are returned.

The $pdf operation returns a comprehensive patient health export as a downloadable PDF. Unlike $summary which generates a curated IPS document, $pdf maps all resources directly from $everything — every resource type returned is rendered; nothing is silently dropped.

When called with a wildcard $PATIENT_ID, the response is a stitched PDF — one branded section per connected source, merged into a single file:

• Payer and provider connections contribute a structured FHIR data section, plus any attached clinical documents (DocumentReference) from that source
• TEFCA QHIN connections contribute C-CDA clinical documents stitched into one PDF per facility

Sections included (structured FHIR)

DocumentReference rendering

Clinical documents are stored as DocumentReference resources. Document content is sourced from content[].attachment.data (inline base64) when present, or fetched from content[].attachment.url (a signed URL on binary.flexpa.com) as a fallback. The renderer dispatches by content type:

In practice, documents arrive as application/xml (C-CDA), application/pdf, or application/rtf. All content types are rendered — nothing is silently dropped.

The response has Content-Type: application/pdf and Content-Disposition: attachment; filename="{patientId}.pdf".

The $health-cards-issue operation creates a SMART Health Card containing the patient's health data as a verifiable credential. This operation generates a digitally signed JWT that packages the patient's FHIR data according to the SMART Health Cards specification.

The operation always uses the patient's complete data set (equivalent to Patient/$everything), ensuring comprehensive health information is included in the credential.

The $expunge operation deletes all resources in a specific Patient resource compartment. This operation performs a "hard" delete, meaning all data, including resource history, is permanently removed from the server.

Once the data is deleted, any subsequent FHIR requests to retrieve the data will return a 404 status code.

The ViewDefinition $run operation does the heavy lifting of parsing FHIR data for you. Define the data your application needs, and get it back as JSON or CSV that's ready to use.

When to use this:

• You need specific fields from ExplanationOfBenefit, Patient, or other resources
• You want data in a format that more closely matches your backend systems and is easier to work with
• You don't want to deal with storing or processing FHIR, you just want directly actionable healthcare data

The operation accepts a ViewDefinition resource that specifies what to extract, then queries the data and returns the structured response.

JSON response (default):

Returns an object with rows (array of extracted data), optional link (pagination), and resourceCount (number of source resources processed). When more pages exist, a Link header in RFC 5988 format with rel="next" is also returned (in addition to the body link array).

CSV response (_format=csv):

Returns plain CSV text. Pagination info is in response headers:

• Link: RFC 5988 format with rel="next" (returned for both JSON and CSV)
• X-Next-Link: Direct URL to next page (CSV only)
• X-Resource-Count: Number of source resources (CSV only)

CapabilityStatement is a conformance FHIR Resource that is used to understand the exact capabilities that a FHIR server makes available. The CapabilityStatement resource is used to describe the features and capabilities of a FHIR server in a machine-readable way. CapabilityStatement is a base FHIR resource.

Flexpa's CapabilityStatement is available at the /fhir/metadata route. View it here.

#Helpful capabilities

We've highlighted the following capabilities to provide extra convenience to developers when querying data. The following examples are defined per-resource.

• interaction is an array of objects that describe the valid operations that can be performed on the resource.
• searchInclude is an array of strings that describe the valid values that can be used with the _include search param.
• searchParam is an array of objects that describe the valid params that the server accepts in a URL query string.
• operation is an array of objects that describe the FHIR operations supported on the resource. Currently only the Patient resource declares this array, exposing the $everything and $summary operations.

All the FHIR resources that Flexpa supports have both a read and search-type operation, which means that they can be both read and searched. You can find the interaction array in the CapabilityStatement resource.

The searchInclude array describes the valid values that can be used with the _include search param. Each value is a string with the format [Resource]:[field], where [Resource] is the resource type and [field] is the field name. For example, to include the care-team field of an ExplanationOfBenefit resource in the search response, you would use the value ExplanationOfBenefit:care-team.

For the search to successfully return a CareTeam resource, the following conditions must be met:

1. A care-team field must be present in the ExplanationOfBenefit resource.
2. The care-team field must contain a relative reference to a CareTeam resource.

To use the _include search param, refer to the Search section.

The searchParam array describes the valid params that the server accepts in a URL query string. These params can be used to filter the search results. The name of the param can be accessed in the name property of each searchParam object in the CapabilityStatement resource.

To filter search results with a searchParam, refer to the Search section.

Flexpa API supports wildcard parameters that can be used in URL query parameters in FHIR API requests.

Wildcards are used as tokens directly in the URL of the API request you make to Flexpa. They are replaced with real values by the API using context provided by the required Patient Access Token.

We currently support one parameter $PATIENT_ID, which references the patient_id belonging to the access_token. Flexpa will replace this token with the correct patient_id when you make an API request to Flexpa.

Flexpa supports search result parameters as a way to modify search results. The following search result query parameters can be used in your search request:

Flexpa supports pagination on the results of a FHIR search request. Pagination can reduce the load on both the client and server.

You can leverage pagination using the following query parameters in your search request:

• _count to control the page size
• _offset to control the page number

In the Flexpa API, the default page size is 20, and the maximum allowed page size is 1000.

Alternatively, if a search result is paginated, the Bundle includes a link array that references other pages in relation to the current page:

• self is the URL of the current page. Always present in link.
• first is the URL of the first page. Always present in link.
• next is the URL of the next page. Only present in link if there is a next page.
• previous is the URL of the previous page. Only present in link if there is a previous page.

For example, to access the next page of resources, make a GET request to the URL indicated by "relation": "next".

Many resources returned by the API will contain references to other resources. A reference is a string that points to the location where the referenced resource can be retrieved. For instance, a Patient may contain a reference to an Organization or a Practitioner.

References can be categorized into one of three types, each of which require a different approach to resolve:

• Relative
• Internal
• Absolute

#Relative references

Relative references are relative to the base resource. They can be identified by the structure [resourceType]/[id]. You can resolve a relative reference by appending the value of the reference string to the base URL in a subsequent GET request.

#Internal references

Internal references point to a "contained" resource that is directly embedded within the base resource. They can be identified by a # prefix. You can access the contained resource in the contained field by filtering for the matching id.

#Absolute references

Absolute references are standalone URLs. They can be identified by any valid URI prefix, but are typically prefixed by either http, https or urn. You may be able request more data using the URL in its entirety. Note that this request will be to a FHIR API separate from Flexpa's.

For more information on references in FHIR, please refer to the FHIR References documentation.

When a request is unsuccessful, Flexpa API attempts to return an OperationOutcome FHIR R4 Resource. If the Endpoint connected by the patient during authorization returns an OperationOutcome Flexpa API returns it directly. If the endpoint does not return an OperationOutcome, Flexpa API substitutes the actual response with a Flexpa-generated OperationOutcome to represent the error.

Your application code should be prepared to handle the following issue.code values:

To protect the stability of the API, requests are rate limited. When your application exceeds the available request quota, the Flexpa API responds with a 429 Too Many Requests status code and an OperationOutcome with an issue.code of throttled.

Every rate limited response carries a backoff signal in its headers:

Treat a throttled 429 as retryable: wait at least Retry-After seconds, then retry the request. Retrying sooner — or retrying without any backoff — extends the throttle window and delays recovery. Other 4xx responses are final and should not be retried unchanged.

A 429 with an issue.code of transient is not a rate limit — it indicates an initial sync is still in progress (see Errors).

Healthcare data sources reference coding systems inconsistently in their FHIR implementations. Flexpa's code system normalization transform resolves these inconsistencies so you can match on a single canonical URI per code system. This transform:

1. Resolves system URIs: Maps nonstandard URIs, OIDs, and common variants (e.g., wrong case, http vs https, trailing .html) to canonical URIs
2. Disambiguates by code format: Distinguishes ICD-10-CM (diagnosis) from ICD-10-PCS (procedure) when both appear under a generic ICD-10 URI, and corrects CPT codes miscategorized under ICD-10 URIs
3. Standardizes code values: Reformats NDC codes to the standard 5-4-2 hyphenated format with zero-padding (e.g., 1234-5678-90 → 01234-5678-90)

#Benefits

• Simplified queries: Match on canonical URIs without accounting for endpoint-specific variations
• Accurate classification: Diagnosis and procedure codes are assigned to the correct code system
• Consistent formats: Code values like NDC follow a single standard format

#How it works

A set of global rules fixes common OID and URI variants for SNOMED, LOINC, RxNorm, CPT, ICD-10-CM, and HCPCS across all resource types in the bundle. On ExplanationOfBenefit resources, additional rules resolve endpoint-specific and legacy URI variants, disambiguate codes like ICD-10-CM and ICD-10-PCS based on code format, and reformat NDC code values.

The terminology reference lists all supported code systems and their canonical URIs.

Flexpa adds standardized tags to all FHIR resources to provide consistent tracking and identification information. These tags help trace the origin of resources and provide additional context for your application.

Each resource is automatically tagged with the following metadata:

1. Consent ID: Unique identifier of the consent (OAuth authorization) that this data belongs to
2. Patient Authorization ID: Unique identifier of the patient authorization that sourced this data
3. Endpoint ID: Identifier of the health plan or provider endpoint that supplied the data
4. Application ID: Your application's identifier within the Flexpa system
5. Patient Authorization Mode: Whether the authorization was in TEST or LIVE mode
6. Authorization Type: The method used for authorization (e.g., OAUTH)

#Benefits

• Traceability: Easily identify the source of each resource in your system
• Filtering: Filter and organize resources by their origin or authorization type
• Auditing: Maintain a clear data lineage for compliance and record-keeping
• Operational Insights: Track which endpoints and authorization methods are providing your data

#How It Works

The tags are added during data processing as part of the Flexpa transform pipeline and require no configuration. They're stored in the resource's meta.tag array as standard FHIR Coding objects, each with a Flexpa-specific system URI.

Each tag uses a specific system URL that identifies its purpose. You can use these system URLs to query for specific tags or filter resources programmatically.

The Identifiers transform systematically replaces all resource IDs with deterministic UUIDv5 identifiers to ensure consistent and collision-free data handling across different health plans and authorizations. This transform:

1. Preserves Original IDs: Stores the original source ID in the resource's identifier array
2. Creates Deterministic IDs: Generates new IDs using UUIDv5 namespacing that remains consistent across syncs
3. Updates References: Updates all references within the bundle to use the new IDs
4. Maintains Relationships: Preserves the referential integrity between resources

#Benefits

• Consistency: Eliminates ID collisions between different payers using the same ID formats
• Determinism: Same resource from the same payer will always get the same ID
• Traceability: Original IDs are preserved in the identifier array for tracking
• Interoperability: Standardized ID format works across different systems and integrations

#How It Works

The Identifiers transform uses UUIDv5 to deterministically generate UUIDs. The input for the UUID is formed by concatenating, in order, the source (the endpoint ID, or the identity provider for identity-based flows such as TEFCA/IAL2), the resource type, and the original source ID. A separate UUID is generated for the Patient resource belonging to the consenting patient and used as the namespace.

This approach ensures that:

• The same resource will always receive the same ID when synced again
• Resources from different patients remain distinct even if their original IDs were identical
• References between resources remain intact with the updated IDs

The References transform ensures that all FHIR references between resources are properly structured, resolvable, and consistent. This transform:

1. Updates Resource IDs: Ensures all references point to the new UUIDv5 IDs created by the Identifiers transform
2. Resolves NPI References: Expands NPI identifiers into proper resource references as part of the NPIs transform
3. Handles Different Reference Types: Works with all reference formats including relative, internal, and absolute references
4. Preserves Source URLs: Maintains original reference information by adding source and fullUrl metadata

#Benefits

• Complete Navigation: Users can follow references between resources without broken links
• Consistent Referencing: All references follow a standardized format
• Traceability: Original source URLs are preserved for auditing and debugging
• Proper FHIR Structure: References comply with FHIR specifications

#How It Works

The References transform operates in multiple stages.

First, during the Identifiers transform, all references within resources are updated to use the new UUIDv5 IDs.

Second, during the NPI transform, identifiers with NPIs are expanded into full references to Provider resources.

Finally, during sourcing, fullUrl and source metadata are added to preserve origin information.

The National Provider Identifier (NPI) transform enhances FHIR bundles by enriching provider information using NPI references found in the data.

While enabled, when an NPI is detected in a FHIR resource Flexpa will:

1. Identify NPIs within the bundle
2. Look up detailed provider information from those NPIs using the National Plan & Provider Enumeration System (NPPES)
3. Expand NPI references in the bundle to include full provider details
4. Backfill provider information such as names, addresses, specialties, and contact information

This transform works with both Practitioner and Organization resources, enhancing references in resources like Patient, Coverage, and ExplanationOfBenefit.

#Benefits

• Richer Data: Adds comprehensive provider details that may be missing in the original data
• Consistent Provider Information: Standardizes provider data across different payers and sources
• Improved User Experience: Enables applications to display detailed provider information without additional lookups

#How It Works

When enabled for your application, the NPI transform runs during data processing and works in three phases—reference expansion, data backfilling, and resource resolution.

• Reference Expansion – Converts bare NPI identifiers into full FHIR references and, when needed, creates the corresponding Practitioner or Organization resource.
• Data Backfilling – Enriches those provider resources with names, addresses, telecom details, and specialties sourced from NPPES.
• Resource Resolution – Revisits the bundle and rewires related resources so they point to the newly enriched provider entries, ensuring every resource has a proper, navigable reference path.

The Medications transform enhances FHIR bundles by creating MedicationRequest resources from pharmacy claims data found in ExplanationOfBenefit resources. This transform:

1. Identifies pharmacy claims in ExplanationOfBenefit resources
2. Extracts medication information from these claims
3. Creates structured MedicationRequest resources with proper references
4. Maintains bidirectional linkage between the source claims and derived medication requests

This process ensures that medication information is consistently available as MedicationRequest resources, even when the original payer API doesn't directly expose this data in that format.

#Safety Notice

MedicationRequest resources derived from pharmacy claims may not indicate medications that were actually dispensed or taken. Claims may have been denied or partially fulfilled. Check the associated ExplanationOfBenefit resources (in supportingInformation) for claim adjudication status.

#Benefits

• Improved Medication Data Access: Provides a standardized way to access medication information through the MedicationRequest resource type
• Connected Resources: Maintains proper references between medication requests and their source claims
• Consistent Experience: Creates a uniform experience across different payers, regardless of their underlying API implementation

#How It Works

The Medications transform occurs automatically during data processing and includes:

• Pharmacy Claim Identification: Detects pharmacy claims in ExplanationOfBenefit resources by checking for pharmacy claim types
• Medication Information Extraction: Pulls medication codes, dates, and other details from the claims' productOrService fields
• Resource Creation: Generates MedicationRequest resources with status: "unknown" (indicating that the fulfillment status is unknown) and intent: "order" (indicating it was a medication order)
• Reference Management: Creates explicit bidirectional references:
  • Adds supportingInformation reference from MedicationRequest to source ExplanationOfBenefit
  • Adds prescription reference from ExplanationOfBenefit to the MedicationRequest
  • Includes derivation-reference extension to clearly mark resources created through this transform
• Deduplication: When multiple claims contain the same medication code, creates a single MedicationRequest with references to all source claims

The Conditions transform automatically adds chronicity and clinical classification data to FHIR Condition resources using two datasets from AHRQ's Healthcare Cost and Utilization Project (HCUP). For every Condition with an ICD-10-CM code, Flexpa:

1. Classifies the condition as Chronic, Not Chronic, or Unknown using the Chronic Condition Indicator Refined (CCIR) dataset
2. Maps the condition to one or more of 552 CCSR clinical categories across 22 body systems using the Clinical Classifications Software Refined (CCSR) dataset

#Benefits

• Filter by chronicity: Identify chronic conditions without maintaining your own lookup tables
• Group by body system: Query conditions by clinical domain (e.g., circulatory, respiratory, endocrine)

#How It Works

• Chronicity extension: Added to Condition.extension using http://hl7.org/fhir/StructureDefinition/condition-related with a valueCoding from system https://api.flexpa.com/fhir/StructureDefinition/condition-chronicity. Codes: C (Chronic), NC (Not Chronic), U (Unknown).
• CCSR category codings: Appended to Condition.code.coding with system https://hcup-us.ahrq.gov/toolssoftware/ccsr/ccs_refined.jsp. Each coding includes the CCSR category code and description.
• Body system categories: Appended to Condition.category as CodeableConcepts with the same CCSR system URI. Body systems are derived from the 3-letter prefix of each CCSR category code (e.g., END for Endocrine).

The Validation transform uses the FHIR $validate operation to validate incoming resources and automatically fix common issues in a non-destructive way. Flexpa automatically:

1. Validates resources ingested by our pipeline
2. Applies non-destructive corrective fixes, such as marking required fields with a data-absent-reason when they are unknown

#Benefits

• Semantic Clarity: Clearly communicates when data is truly missing from a source system
• Integrity: Maintains data accuracy without accidental data loss
• Interoperability: Improves compatibility with downstream FHIR systems and consumers

#How it works

1. $validate Operation: Each incoming Bundle is sent to the FHIR $validate endpoint.
2. Parse OperationOutcome: The resulting OperationOutcome is inspected for structural error issues.
3. Auto-correction: Common issues are fixed non-destructively (e.g., convert scalars to arrays).
4. Add data-absent-reason: Missing required fields are annotated with the standard data-absent-reason extension and a value of unknown

The Provider Directory is a searchable database of healthcare providers in the United States, powered by the National Plan and Provider Enumeration System (NPPES) data. You can use this directory to search for providers by NPI, name, specialty, location, and other criteria.

The Provider Directory is available through the FHIR API and allows you to:

• Search for providers using FHIR's standard search capabilities
• Retrieve detailed provider information including specialties, practice locations, and contact details
• Access provider data without requiring patient consent

Access to the Provider Directory requires an Application Access Token, which you can obtain through the Token Endpoint.

Individual healthcare providers can be accessed through the Practitioner resource. Each provider's National Provider Identifier (NPI) is carried in identifier (use the identifier search parameter to look up a provider by NPI). The resource id is a Flexpa-assigned UUID used for read-by-id and references. Each Practitioner includes details about their credentials, contact information, and practice locations.

Healthcare organizations such as hospitals, clinics, and group practices can be accessed through the Organization resource. The resource id is a Flexpa-assigned identifier; an organization's National Provider Identifier (NPI) is exposed in identifier and is matched via the identifier search parameter. Each organization includes details about their type, contact information, and locations.

At Flexpa, our API is core to everything we do. If you're excited to work with us, applying by API is the best way to get our attention.

Find out more about how we work in the Flexpa OS.