FHIR API Reference
#Records
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
- Patients consent to transfer health data through Flexpa Consent to your application
- Your server exchanges the consent for an access token
- Use these tokens to make authenticated requests to Flexpa's FHIR API endpoints
- 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.
Base URL
https://api.flexpa.com
#API Keys
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 pk_live_. They are used only in server-side code and must be kept secure.
API Key Authorization Header
Authorization: Basic ${base64_encoded_credentials}
Required for OAuth token requests.
#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
| If you need to... | Use this token type |
|---|
| Access a specific patient's data | Patient Access Token |
| Make application-level API calls without patient context | Application Access Token |
Access API endpoints like /fhir/metadata | Either token type works |
Access Token Authorization Header
Authorization: Bearer eyJhbGc...
Required for all FHIR API requests.
#Patient Access Token
Patient Access Tokens are created when a patient authorizes your application through Flexpa Consent and you complete the exchange step. These tokens are tied to a specific patient's identity and grant access to that patient's health data.
- Used for accessing patient-specific health records
- Tied to a specific patient identity - all API responses are automatically filtered
- Valid for 24 hours
- Obtained from the exchange step
- Can be refreshed with a refresh token for
MULTIPLE usage authorizations
- You can inspect token details using the introspect endpoint
JWT claims
- jti
A unique identifier for the JWT (JSON Web Token). Generated as a random UUID to identify this specific token.
- sub
Subject identifier. Contains the Consent ID.
- patient
FHIR Patient resource identifier in the format Patient/id. This claim is specific to Patient Access Tokens.
- client_id
OAuth 2.0 client identifier of the application that requested the token.
- iat
Time at which the JWT was issued, in seconds since Unix epoch.
- exp
Expiration time in seconds since Unix epoch. Patient Access Tokens expire 24 hours after issuance.
#Application Access Token
Application Access Tokens operate at the application level without any patient context. You obtain these through the OAuth 2.0 Client Credentials flow, using your application's API keys.
- Used for accessing application-level resources without patient context
- Valid for 30 minutes
- Obtained through Client Credentials grant flow on the Token Endpoint
- Cannot be refreshed (request a new token when needed)
- Used to access the Provider Directory
- Live mode keys only: Application access tokens can only be created using live mode API keys
JWT claims
- jti
A unique identifier for the JWT (JSON Web Token). Generated as a random UUID to identify this specific token.
- sub
Subject identifier. For Application Tokens, this matches the client_id (application ID).
- client_id
OAuth 2.0 client identifier of the application that requested the token.
- iat
Time at which the JWT was issued, in seconds since Unix epoch.
- exp
Expiration time in seconds since Unix epoch. Application Access Tokens expire 30 minutes after issuance.
#Patient Authorizations
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:
- They select their health plan or provider
- They authenticate with that organization
- They explicitly consent to share specific data with your application
- 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.
Authorization states
- CREATED
The initial state when a patient authorization record is created but before the authentication process has begun.
- AUTHORIZING
The patient is in the process of authenticating with their health plan but has not yet completed the process.
- AUTHORIZED
The patient has successfully authenticated with their health plan and granted consent, but the authorization has not yet been exchanged for an access token.
- EXCHANGED
The public token has been exchanged for an access token, and the patient's data is being synchronized.
- REFRESHED
For MULTIPLE usage authorizations only. The access token has been refreshed at least once using a refresh token.
- ERRORED
An error occurred during the authorization or data synchronization process.
- ABANDONED
The patient started the authorization process but did not complete it. This could be due to various reasons like timeout, closing the window, or navigation away.
- BOUNCED
The authorization process was rejected by the health plan's system, possibly due to invalid credentials or other issues.
- REVOKED
The authorization has been explicitly revoked by the patient or your application using the revoke endpoint.
#Request ID
Each API request has an associated request identifier.
You can find this value in the response headers, under X-Request-Id.
If you need help debugging a request, please include the Request Id when contacting support.
#Sync Job States
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.
During the initial sync period (typically less than 1 minute), FHIR API requests may return a 429 status code. Once the sync is complete (status: COMPLETED), patient data becomes available for querying. You can monitor the current sync state through the sync.state property returned in the exchange response or via the introspect endpoint.
Sync job states
- CREATED
The sync job has been created after successful patient authorization. This is its initial state.
- WAITING
The sync job is queued for processing and will begin retrieving data from the health plan's API soon.
- ACTIVE
The sync job is currently retrieving and processing the patient's health data from their health plan.
- FAILED
The sync job encountered an error and was unable to complete. This may require the patient to re-authorize.
- COMPLETED
The sync job has successfully retrieved and processed all available patient data, which is now available through the FHIR API.
#FHIR 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)
- 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:
GEThttps://api.flexpa.com/fhir/[Resource]/:id
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.
Many resources returned by the API will contain references to other resources.
For more information on how to handle references, see the Referenced Resources section.
Request parameters
- identifierstring
The identifier of the resource to be retrieved - used in the last part of the URL path segment
Response fields
- resourceTypestring
Reads return an individual resource, so the resource type is expected to correspond to the resource you are reading
Error codes
- transient429 status code
The API is expected to return a 429 status code until the data is ready to be retrieved.
This error is returned by the API while in the initial sync period, which typically lasts less than 1 minute.
You will need to implement retry logic to handle this error. If you are using the Node SDK which we demonstrate in our Quickstart guide, retry logic is already built in and you don't need to implement it yourself.
- processing422 status code
- The API is expected to return a 422 when Flexpa fails to synchronize any resources from the Endpoint for the requested Patient. Please re-authorize or reach out to support.
ACCESS_TOKEN=flexpa-link-access-token
curl https://api.flexpa.com/fhir/Coverage/123 \
-H "Authorization: Bearer $ACCESS_TOKEN"
Response
{
"resourceType": "Coverage",
"id": "123"
}
GEThttps://api.flexpa.com/fhir/[Resource]
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.
Many resources returned by the API will contain references to other resources.
For more information on how to handle references, see the Referenced Resources section.
Request parameters
- _includestring
The referenced resources to include in the search response.
Only applies to relative references.
The value of the searchInclude parameter has the format [Resource]:[field], for example Patient:general-practitioner.
For more information on available searchInclude parameters, please refer to the CapabilityStatement.
- _revincludestring
Like _include but intstead of including the resources referenced within the searched-for resource, include resources that may reference the searched resource.
The value of the searchRevInclude parameter has the format [Resource]:[field], for example Provenance:target.
- [searchParam]string
To filter the search results server-side, you can use any of the available search parameters for the resource type you are searching for.
For more information on available searchParam parameters, please refer to the CapabilityStatement.
Search results can also be modified by certain search result parameters.
For more information on available search result parameters, see the Search Result Parameters section.
Response fields
- resourceTypestring
Searches return a Bundle resource type
- entryarray
An array of FHIR resources expected to match the resource type of the search
Error codes
- transient429 status code
The API is expected to return a 429 status code until the data is ready to be retrieved.
This error is returned by the API while in the initial sync period, which typically lasts less than 1 minute.
You will need to implement retry logic to handle this error. If you are using the Node SDK which we demonstrate in our Quickstart guide, retry logic is already built in and you don't need to implement it yourself.
- processing422 status code
- The API is expected to return a 422 when Flexpa fails to synchronize any resources from the Endpoint for the requested Patient. Please refresh again or reach out to support.
Request
ACCESS_TOKEN=flexpa-link-access-token
curl https://api.flexpa.com/fhir/ExplanationOfBenefit \
-H "Authorization: Bearer $ACCESS_TOKEN"
Response
{
"resourceType": "Bundle",
"id": "22f61d0877b54b2a8a2feb57bfe2c462",
"entry": [
{
"resource": {
"resourceType": "ExplanationOfBenefit",
"id": "123"
}
},
{
"resource": {
"resourceType": "ExplanationOfBenefit",
"id": "456"
}
}
]
}
GEThttps://api.flexpa.com/fhir/Patient/$PATIENT_ID/$everything
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:
This request returns large Bundles. The client should be prepared to handle a potentially large single response.
Response fields
- ResponseBundle
Patient $everything returns a Bundle that contains all resources that reference the Patient resource.
GET
/fhir/Patient/$PATIENT_ID/$everythingACCESS_TOKEN=flexpa-link-access-token
curl 'https://api.flexpa.com/fhir/Patient/$PATIENT_ID/$everything' \
-H "Authorization: Bearer $ACCESS_TOKEN"
Response
{
"resourceType": "Bundle",
"entry": [
{ "resource": {"resourceType": "Patient", ...} },
{ "resource": {"resourceType": "Coverage", ...} },
{ "resource": {"resourceType": "ExplanationOfBenefit", ...} },
]
}
GEThttps://api.flexpa.com/fhir/Patient/$PATIENT_ID/$summary
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.
| Alias | LOINC code | Section |
|---|
allergies | 48765-2 | Allergies |
medications | 10160-0 | Medications |
problems | 11450-4 | Problem list |
immunizations | 11369-6 | Immunizations |
procedures | 47519-4 | Procedures |
results | 30954-2 | Results |
vitalsigns | 8716-3 | Vital signs |
socialhistory | 29762-2 | Social history |
devices | 46264-8 | Devices |
planofcare | 18776-5 | Plan of treatment |
functionalstatus | 47420-5 | Functional status |
pastillness | 11348-0 | History of past illness |
pregnancy | 10162-6 | Pregnancy history |
advancedirectives | 42348-3 | Advance directives |
The IPS is more compact than $everything — it returns a curated clinical summary rather than the full patient compartment. Use $everything when you need all available data, and $summary when you need a structured clinical overview. When _section is provided, excluded sections remain in the Composition (preserving the IPS structure) but contain no entries and are marked as withheld. Only resources referenced by included sections are present in the Bundle. Patient, Composition, and author resources are always retained.
Request query parameters
- _sectionstring
One or more LOINC section codes or aliases to include. Repeat for multiple sections. When omitted, all sections are returned.
Response fields
- ResponseBundle
A Bundle of type document containing a Composition resource, referenced clinical resources organized into IPS sections, and a DocumentReference with a rendered PDF of the summary. The Composition always includes all 14 sections — sections with data contain entry references; sections without data or excluded by _section contain an emptyReason.
GET
/fhir/Patient/$PATIENT_ID/$summaryACCESS_TOKEN=flexpa-link-access-token
curl 'https://api.flexpa.com/fhir/Patient/$PATIENT_ID/$summary' \
-H "Authorization: Bearer $ACCESS_TOKEN"
Filtered request
GET
/fhir/Patient/$PATIENT_ID/$summary?_section=...ACCESS_TOKEN=flexpa-link-access-token
curl 'https://api.flexpa.com/fhir/Patient/$PATIENT_ID/$summary?_section=allergies&_section=medications' \
-H "Authorization: Bearer $ACCESS_TOKEN"
Response
{
"resourceType": "Bundle",
"type": "document",
"timestamp": "2026-02-19T00:00:00.000Z",
"meta": {
"security": [{ "system": "http://terminology.hl7.org/CodeSystem/v3-Confidentiality", "code": "N" }]
},
"entry": [
{
"resource": {
"resourceType": "Composition",
"title": "International Patient Summary",
"type": { "coding": [{ "system": "http://loinc.org", "code": "60591-5" }] },
"section": [
{
"title": "Allergies",
"code": { "coding": [{ "system": "http://loinc.org", "code": "48765-2" }] },
"entry": [{ "reference": "AllergyIntolerance/allergy-1" }]
},
{
"title": "Medications",
"code": { "coding": [{ "system": "http://loinc.org", "code": "10160-0" }] },
"entry": [{ "reference": "MedicationRequest/med-1" }]
},
{
"title": "Vital Signs",
"code": { "coding": [{ "system": "http://loinc.org", "code": "8716-3" }] },
"emptyReason": {
"coding": [{ "system": "http://terminology.hl7.org/CodeSystem/list-empty-reason", "code": "unavailable" }]
}
}
]
}
},
{ "resource": { "resourceType": "Patient", "..." : "..." } },
{ "resource": { "resourceType": "Organization", "..." : "..." } },
{ "resource": { "resourceType": "AllergyIntolerance", "..." : "..." } },
{ "resource": { "resourceType": "MedicationRequest", "..." : "..." } },
{
"resource": {
"resourceType": "DocumentReference",
"status": "current",
"type": { "coding": [{ "system": "http://loinc.org", "code": "60591-5", "display": "Patient summary Document" }] },
"content": [{ "attachment": { "contentType": "application/pdf", "data": "base64..." } }]
}
}
]
}
POSThttps://api.flexpa.com/fhir/Patient/:id/$health-cards-issue
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 health card is returned as a signed JWT string within a Parameters resource, not as a raw SMART Health Card file. The JWT can be converted to a QR code or shared directly as a verifiable credential.
Request headers
- Authorizationstring
An Authorization: Bearer header value must be presented with a Patient Access Token
Request path parameters
- idstring
The identifier of the patient - use $PATIENT_ID to automatically reference the authenticated patient
Request body
- resourceTypestring
Must be Parameters
- parameterarray
Array containing exactly one parameter object
- namestring
Must be credentialType
- valueUristring
Must be Patient/$everything (currently the only supported credential type)
Response fields
- ResponseParameters
Returns FHIR Parameters resource containing the SMART Health Card
- parameterarray
Array containing exactly one parameter object
- namestring
Will be verifiableCredential
- valueStringstring
The signed SMART Health Card as a JWT string
POST
/fhir/Patient/:id/$health-cards-issueACCESS_TOKEN=flexpa-link-access-token
curl 'https://api.flexpa.com/fhir/Patient/$PATIENT_ID/$health-cards-issue' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"resourceType": "Parameters",
"parameter": [
{
"name": "credentialType",
"valueUri": "Patient/$everything"
}
]
}'
Request Body
{
"resourceType": "Parameters",
"parameter": [
{
"name": "credentialType",
"valueUri": "Patient/$everything"
}
]
}
Response
{
"resourceType": "Parameters",
"parameter": [
{
"name": "verifiableCredential",
"valueString": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjNLZmRnLVh3UC03Z..."
}
]
}
POSThttps://api.flexpa.com/fhir/Patient/:patientId/$expunge
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.
Request headers
- AuthorizationstringRequired
An Authorization: Bearer header value must be presented with a Patient Access Token
Request parameters
- patientIdstring
The ID of the patient whose data you want to delete.
This ID must match the patient ID of the access token and can be retrieved with a search request for the Patient resource.
There is an option to use the patient wildcard parameter to automatically match the patient ID in the access token.
Response fields
- ResponseBundle
The Patient $expunge operation returns an OperationOutcome resource, indicating the success or failure of the expunge request.
Error codes
- transient429 status code
The API is expected to return a 429 status code until the data is ready to be retrieved.
The API returns this error during the initial sync period, which typically lasts less than 1 minute.
Data cannot be expunged until the initial sync period has passed.
POST
/fhir/Patient/$PATIENT_ID/$expungeACCESS_TOKEN=flexpa-link-access-token
curl 'https://api.flexpa.com/fhir/Patient/$PATIENT_ID/$expunge' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-X POST
Response
{
"resourceType": "OperationOutcome",
"id": "accepted",
"issue": [
{
"severity": "information",
"code": "informational",
"details": {
"text": "Accepted"
},
"diagnostics": "http://medplum.flexpa.com/fhir/R4/job/15c72fcc-267e-4372-a85e-26fa20b01634/status"
}
],
"extension": [
{
"url": "https://medplum.com/fhir/StructureDefinition/tracing",
"extension": [
{
"url": "requestId",
"valueUuid": "175885a0-d396-4d1d-9c9d-a618f06cfdc8"
},
{
"url": "traceId",
"valueUuid": "5e18c528-a74a-4dac-9cec-b35a2ce33c3e"
}
]
}
]
}
POSThttps://api.flexpa.com/fhir/ViewDefinition/$run
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.
Need help getting started? We're FHIR experts and can help you craft a ViewDefinition that extracts exactly the data you need. Reach out to your Flexpa contact or our support team.
Request
curl -X POST "https://api.flexpa.com/fhir/ViewDefinition/\$run" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"resourceType": "Parameters",
"parameter": [
{
"name": "viewResource",
"resource": {
"resourceType": "ViewDefinition",
"name": "patient_basics",
"status": "active",
"resource": "Patient",
"select": [{
"column": [
{ "name": "id", "path": "id" },
{ "name": "family_name", "path": "name.first().family" },
{ "name": "given_name", "path": "name.first().given.first()" },
{ "name": "birth_date", "path": "birthDate" }
]
}]
}
}
]
}'
#Request body
The request body is a FHIR Parameters resource containing the operation parameters.
- viewResourceViewDefinitionRequired
The ViewDefinition resource specifying what fields to extract. Must be provided inline (not by reference).
- patientReference
Optional. Filter results to a specific patient (e.g., Patient/123). Primarily for use with Application Access Tokens.
- groupReference[]
Optional. Filter results to patients in one or more Groups. Can be repeated. Not supported for patient-scoped tokens.
- _formatcode
Output format: json (default) or csv.
- _limitinteger
Maximum number of output rows to return.
- _sinceinstant
Filter to resources updated since this timestamp.
- headerboolean
For CSV output, whether to include the header row. Defaults to true.
#Query parameters
- _countstring
Number of source resources to process per page.
- _offsetstring
Pagination offset for source resources.
#Response
JSON response (default):
Returns an object with rows (array of extracted data), optional link (pagination), and resourceCount (number of source resources processed).
CSV response (_format=csv):
Returns plain CSV text. Pagination info is in response headers:
Link: RFC 5988 format with rel="next"X-Next-Link: Direct URL to next pageX-Resource-Count: Number of source resources
{
"rows": [
{
"id": "a85f4c92-...",
"family_name": "Smith",
"given_name": "John",
"birth_date": "1985-03-15"
}
],
"resourceCount": 1
}
For complete ViewDefinition syntax and FHIRPath expressions, see our Parsing FHIR guide.
GEThttps://api.flexpa.com/fhir/metadata
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.
curl https://api.flexpa.com/fhir/metadata
Response
{
"resourceType": "CapabilityStatement",
"url": "https://api.flexpa.com/fhir/metadata",
"title": "Flexpa Capability Statement",
"date": "2023-11-01",
"publisher": "Flexpa",
"rest": [
{
"mode": "server",
"resource": [
{ "type": "Patient", ... },
{ "type": "Coverage", ... },
{ "type": "ExplanationOfBenefit", ... },
...
]
}
]
}
#Interaction
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.
Interaction
{
"resourceType": "CapabilityStatement",
"url": "https://api.flexpa.com/fhir/metadata",
"rest": [
{
"mode": "server",
"resource": [
{
"type": "Practitioner",
"interaction": [
{
"code": "read",
},
{
"code": "search-type",
}
]
}
]
}
]
}
#Search Include
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:
- A
care-team field must be present in the ExplanationOfBenefit resource.
- The
care-team field must contain a relative reference to a CareTeam resource.
To use the _include search param, refer to the Search section.
Search Include
{
"resourceType": "CapabilityStatement",
"url": "https://api.flexpa.com/fhir/metadata",
"rest": [
{
"mode": "server",
"resource": [
{
"type": "ExplanationOfBenefit",
"searchInclude": [
"ExplanationOfBenefit:care-team",
]
}
]
}
]
}
#Search Param
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.
Search Param
{
"resourceType": "CapabilityStatement",
"url": "https://api.flexpa.com/fhir/metadata",
"rest": [
{
"mode": "server",
"resource": [
{
"type": "Condition",
"searchParam": [
{
"name": "onset-age",
"definition": "http://hl7.org/fhir/SearchParameter/Condition-onset-age",
"type": "quantity"
}
]
}
]
}
]
}
#Wildcard Parameters
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.
Wildcard in Patient Read
ACCESS_TOKEN=flexpa-link-access-token
curl 'https://api.flexpa.com/fhir/Patient/$PATIENT_ID' \
-H "Authorization: Bearer $ACCESS_TOKEN"
#Search Result Parameters
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:
_totalstringThe _total query parameter will include in the bundle the number of resources that match the search parameters. It is not always visible on the bundle. The possible values for the _total search result paramter are:
none: Flexpa will not include the total in the responseaccurate: Flexpa will provide the exact total of matching resources, if available. Note that this may be more server intensive.estimate: Flexpa will provide a rough estimate of the number of matching resources, if available.
_sortstringThe _sort parameter is used to sort results in priority order based on a comma-separated list of search parameters, for example status,-date,category.
If the _sort value starts with -, then the results are returned in decreasing order, otherwise they are returned in increasing order.
_summarystringThe _summary parameter returns a portion of a resource's elements in order to help optimize queries for only the essential information.
Supported values for _summary are true, which returns only elements that are marked summary in the resource's definition, and count which will return only the count of matching resources, but no other resource details.
_elementsstringThe _elements parameter returns a specified subset of a resource's elements. Specified elements are given as a list of comma separated values, for example _elements=identifier,active,link.
However, more than only requested elements may be returned, including mandatory elements or modifier elements that have values.
_countstringThe _count parameter limits the number of results per page. See Pagination for more information.
Request
GET
/fhir/[Resource]?_total=[none|accurate|estimate]const ACCESS_TOKEN="flexpa-link-access-token";
const searchUrl = "https://api.flexpa.com/fhir/ExplanationOfBenefit?patient=$PATIENT_ID&_total=accurate";
const response = await fetch(searchUrl, {
headers: {
"authorization": `Bearer ${ACCESS_TOKEN}`,
},
});
const searchBundle = await response.json();
Response
{
"resourceType": "Bundle",
"type": "searchset",
"entry": [...],
"total": 11,
"link": [...]
}
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".
GET
/fhir/Condition?_count=3ACCESS_TOKEN=flexpa-link-access-token
curl https://api.flexpa.com/fhir/Condition?_count=3 \
-H "Authorization: Bearer $ACCESS_TOKEN"
Response
{
"resourceType": "Bundle",
"type": "searchset",
"entry": [ ... ],
"link": [
{
"relation": "self",
"url": "https://api.flexpa.com/fhir/Condition?_count=3&_offset=6&_tag=..."
},
{
"relation": "first",
"url": "https://api.flexpa.com/fhir/Condition?_count=3&_offset=0&_tag=..."
},
{
"relation": "next",
"url": "https://api.flexpa.com/fhir/Condition?_count=3&_offset=9&_tag=..."
},
{
"relation": "previous",
"url": "https://api.flexpa.com/fhir/Condition?_count=3&_offset=3&_tag=..."
},
]
}
#Referenced Resources
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 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.
Alternatively, you can conveniently resolve relative references in a single API request by using the _include parameter on a Search operation.
For more information on available searchInclude parameters, please refer to the CapabilityStatement.
#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.
Contained resources in FHIR do not need to be complete resources.
For example, a contained resource may only contain a name field and this is considered valid FHIR.
#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.
Following URLs to external servers is always risky.
Please consider the security implications of doing so and take the appropriate steps to mitigate unintended access to malicious servers, such as an allowlist of trusted servers for example.
Alternatively, the most conservative approach is to avoid following absolute references altogether.
For more information on references in FHIR, please refer to the FHIR References documentation.
Resolving References
const patient = {
"resourceType" : "Patient",
"generalPractitioner" : {
"reference" : "Practitioner/123"
}
};
const ACCESS_TOKEN="flexpa-link-access-token";
const response = await fetch("https://api.flexpa.com/fhir/Practitioner/123", {
headers: {
"authorization": `Bearer ${ACCESS_TOKEN}`,
},
});
const practitioner = await response.json();
Resolved Resource
{
"resourceType" : "Practitioner",
"id" : "123",
"name" : "Dr. Adam Smith"
}
#Errors
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:
Error codes
- processing422 status code
- Processing issues. This is expected to be final (e.g., there is no point resubmitting the same content unchanged).
- transient429 status code
- The API returns a 429 status code while syncing data from the payer. This happens during the initial sync period, typically lasting less than 1 minute. During this time, data cannot be expunged.
- not-supported404 status code
- The interaction, operation, resource or profile is not supported.
- forbidden403 status code
- The user does not have the rights to perform this action.
- exception500+ status code
- An unexpected internal error has occurred.
Error response
{
"resourceType": "OperationOutcome",
"issue": [{
"severity": "error",
"code": "not-supported"
}],
};
Flexpa's transform pipeline automatically enhances FHIR data received from payers, delivering a more consistent, comprehensive, and usable dataset. These transforms are applied to all data retrieved through the Flexpa API without any configuration needed.
Our transform architecture offers several key benefits:
-
Consistent Resource Structure: Normalized formats across all payers, enabling you to build once and support all health plans
-
Enhanced Provider Information: Automatically enriched resources with detailed provider data through NPI resolution
-
Standardized Identifiers: Deterministic UUIDv5 identifiers ensuring consistent identification and preventing collisions
-
Improved Reference Integrity: Standardized references between resources for easier data navigation
The sections below highlight the most significant transforms in our pipeline:
#Code systems
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:
- Resolves system URIs: Maps nonstandard URIs, OIDs, and common variants (e.g., wrong case,
http vs https, trailing .html) to canonical URIs
- 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
- 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.
Before code system normalization
{
"resourceType": "ExplanationOfBenefit",
"diagnosis": [{
"diagnosisCodeableConcept": {
"coding": [{
"system": "urn:oid:2.16.840.1.113883.6.90",
"code": "M54.5"
}]
}
}],
"procedure": [{
"procedureCodeableConcept": {
"coding": [{
"system": "http://hl7.org/fhir/sid/icd-10",
"code": "0SRC0J9"
}]
}
}],
"item": [{
"productOrService": {
"coding": [{
"system": "http://hl7.org/fhir/sid/ndc",
"code": "1234-5678-90"
}]
}
}]
}
After code system normalization
{
"resourceType": "ExplanationOfBenefit",
"diagnosis": [{
"diagnosisCodeableConcept": {
"coding": [{
"system": "http://hl7.org/fhir/sid/icd-10-cm",
"code": "M54.5"
}]
}
}],
"procedure": [{
"procedureCodeableConcept": {
"coding": [{
"system": "http://www.cms.gov/Medicare/Coding/ICD10",
"code": "0SRC0J9"
}]
}
}],
"item": [{
"productOrService": {
"coding": [{
"system": "http://hl7.org/fhir/sid/ndc",
"code": "01234-5678-90"
}]
}
}]
}
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:
- Consent ID: Unique identifier of the consent (OAuth authorization) that this data belongs to
- Patient Authorization ID: Unique identifier of the patient authorization that sourced this data
- Endpoint ID: Identifier of the health plan or provider endpoint that supplied the data
- Application ID: Your application's identifier within the Flexpa system
- Patient Authorization Mode: Whether the authorization was in
TEST or LIVE mode
- 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.
System URLs
- https://fhir.flexpa.com/identifiers/ConsentId
Identifies the consent (OAuth authorization) that this data belongs to
- https://fhir.flexpa.com/identifiers/PatientAuthorizationId
Identifies the unique patient authorization that sourced this data
- https://fhir.flexpa.com/identifiers/EndpointId
Indicates which health plan or provider endpoint supplied the data
- https://fhir.flexpa.com/identifiers/ApplicationId
Identifies your application within the Flexpa system
- https://fhir.flexpa.com/identifiers/PatientAuthorizationMode
Indicates if the authorization was in TEST or LIVE mode
- https://fhir.flexpa.com/identifiers/AuthorizationType
Specifies the method used for authorization (e.g., OAUTH)
Before Tagging Transform
{
"resourceType": "Patient",
"id": "example-patient-id",
"meta": {
"lastUpdated": "2023-05-15T14:30:00Z"
},
"name": [
{
"family": "Smith",
"given": ["John"]
}
]
}
After Tagging Transform
{
"resourceType": "Patient",
"id": "example-patient-id",
"meta": {
"lastUpdated": "2023-05-15T14:30:00Z",
"tag": [
{
"system": "https://fhir.flexpa.com/identifiers/ConsentId",
"code": "f7e23a91-bc45-4d12-9e8f-1a2b3c4d5e6f"
},
{
"system": "https://fhir.flexpa.com/identifiers/PatientAuthorizationId",
"code": "8a350181-3115-49d7-a6aa-8e05b1cab08a"
},
{
"system": "https://fhir.flexpa.com/identifiers/EndpointId",
"code": "a5c22966-244d-4f36-b43a-4d4a619f89cc",
"display": "flexpa-sandbox"
},
{
"system": "https://fhir.flexpa.com/identifiers/ApplicationId",
"code": "062ca646-8d42-4753-9cd1-b39b234dd559"
},
{
"system": "https://fhir.flexpa.com/identifiers/PatientAuthorizationMode",
"code": "TEST"
},
{
"system": "https://fhir.flexpa.com/identifiers/AuthorizationType",
"code": "OAUTH"
}
]
},
"name": [
{
"family": "Smith",
"given": ["John"]
}
]
}
#Identifiers
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:
- Preserves Original IDs: Stores the original source ID in the resource's
identifier array
- Creates Deterministic IDs: Generates new IDs using UUIDv5 namespacing that remains consistent across syncs
- Updates References: Updates all references within the bundle to use the new IDs
- 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 the Resource Type, source ID, and endpoint 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
When working with FHIR data from Flexpa, always use the resource's ID for references rather than trying to reconstruct references from original identifiers.
Before Identifiers Transform
{
"resourceType": "ExplanationOfBenefit",
"id": "123456",
"patient": {
"reference": "Patient/98765"
},
"provider": {
"reference": "Practitioner/PROV001"
}
}
After Identifiers Transform
{
"resourceType": "ExplanationOfBenefit",
"id": "a1b2c3d4-e5f6-5a5a-b5c5-d5e5f5a5b5c5",
"identifier": [
{
"system": "https://api.payer.com/fhir/ExplanationOfBenefit/SourceResourceId",
"value": "123456"
}
],
"patient": {
"reference": "Patient/f9e8d7c6-b5a4-5b5b-c5d5-e5f5a5b5c5d5"
},
"provider": {
"reference": "Practitioner/c9b8a7d6-e5f4-5c5c-d5e5-f5a5b5c5d5e5"
}
}
#References
The References transform ensures that all FHIR references between resources are properly structured, resolvable, and consistent. This transform:
- Updates Resource IDs: Ensures all references point to the new UUIDv5 IDs created by the Identifiers transform
- Resolves NPI References: Expands NPI identifiers into proper resource references as part of the NPIs transform
- Handles Different Reference Types: Works with all reference formats including relative, internal, and absolute references
- 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.
References between resources are a key part of the FHIR standard. Flexpa ensures that all references work properly so you can navigate between related resources.
Before References Transform
{
"resourceType": "Bundle",
"type": "searchset",
"entry": [
{
"resource": {
"resourceType": "ExplanationOfBenefit",
"id": "123456",
"patient": {
"reference": "Patient/98765"
},
"provider": {
"identifier": {
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "1234567890"
}
}
}
}
]
}
After References Transform
{
"resourceType": "Bundle",
"type": "searchset",
"entry": [
{
"fullUrl": "https://api.payer.com/ExplanationOfBenefit/123456",
"resource": {
"resourceType": "ExplanationOfBenefit",
"id": "a1b2c3d4-e5f6-5a5a-b5c5-d5e5f5a5b5c5",
"meta": {
"source": "https://api.payer.com/ExplanationOfBenefit/123456"
},
"patient": {
"reference": "Patient/f9e8d7c6-b5a4-5b5b-c5d5-e5f5a5b5c5d5"
},
"provider": {
"reference": "Practitioner/c9b8a7d6-e5f4-5c5c-d5e5-f5a5b5c5d5e5",
"identifier": {
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "1234567890"
}
}
}
},
{
"fullUrl": "https://api.payer.com/Practitioner/PROV001",
"resource": {
"resourceType": "Practitioner",
"id": "c9b8a7d6-e5f4-5c5c-d5e5-f5a5b5c5d5e5",
"meta": {
"source": "https://api.payer.com/Practitioner/PROV001"
},
"identifier": [
{
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "1234567890"
}
],
"name": [
{
"family": "Smith",
"given": ["John", "A"],
"prefix": ["Dr."]
}
]
}
}
]
}
#NPIs
The National Provider Identifier (NPI) transform enhances FHIR bundles by enriching provider information using NPI references found in the data. When an NPI is detected in a FHIR resource, Flexpa automatically:
- Identifies NPIs within the bundle
- Looks up detailed provider information from those NPIs using the National Plan & Provider Enumeration System (NPPES)
- Expands NPI references in the bundle to include full provider details
- Backfills 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
The NPI transform runs automatically 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.
Before NPI Transform
{
"resourceType": "Bundle",
"type": "searchset",
"entry": [
{
"resource": {
"resourceType": "ExplanationOfBenefit",
"id": "eob-12345",
"provider": {
"identifier": {
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "1234567890"
}
}
}
}
]
}
After NPI Transform
{
"resourceType": "Bundle",
"type": "searchset",
"entry": [
{
"resource": {
"resourceType": "ExplanationOfBenefit",
"id": "a1b2c3d4-e5f6-5a5a-b5c5-d5e5f5a5b5c5",
"provider": {
"reference": "Practitioner/c9b8a7d6-e5f4-5c5c-d5e5-f5a5b5c5d5e5",
"identifier": {
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "1234567890"
}
}
}
},
{
"resource": {
"resourceType": "Practitioner",
"id": "c9b8a7d6-e5f4-5c5c-d5e5-f5a5b5c5d5e5",
"identifier": [
{
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "1234567890"
}
],
"name": [
{
"family": "Smith",
"given": ["John", "A"],
"prefix": ["Dr."]
}
],
"address": [
{
"line": ["123 Main St"],
"city": "Anytown",
"state": "CA",
"postalCode": "12345"
}
],
"telecom": [
{
"system": "phone",
"value": "555-123-4567"
}
],
"qualification": [
{
"code": {
"coding": [
{
"system": "http://nucc.org/provider-taxonomy",
"code": "207R00000X",
"display": "Internal Medicine"
}
]
}
}
]
}
}
]
}
#Medications
Preview: This transform is in preview and is available to enterprise partners.
The Medications transform enhances FHIR bundles by creating MedicationRequest resources from pharmacy claims data found in ExplanationOfBenefit resources. This transform:
- Identifies pharmacy claims in ExplanationOfBenefit resources
- Extracts medication information from these claims
- Creates structured MedicationRequest resources with proper references
- 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
Before Medications Transform
{
"resourceType": "Bundle",
"type": "searchset",
"entry": [
{
"resource": {
"resourceType": "ExplanationOfBenefit",
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/claim-type",
"code": "pharmacy"
}
]
},
"item": [
{
"productOrService": {
"coding": [
{
"system": "http://hl7.org/fhir/sid/ndc",
"code": "12345-6789-01",
"display": "Medication Name 20mg"
}
]
}
}
]
}
}
]
}
After Medications Transform
{
"resourceType": "Bundle",
"type": "searchset",
"entry": [
{
"resource": {
"resourceType": "ExplanationOfBenefit",
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/claim-type",
"code": "pharmacy"
}
]
},
"item": [
{
"productOrService": {
"coding": [
{
"system": "http://hl7.org/fhir/sid/ndc",
"code": "12345-6789-01",
"display": "Medication Name 20mg"
}
]
}
}
],
"prescription": {
"reference": "MedicationRequest/b7c8d9e0-f1a2-3456-bcde-789012345678"
}
}
},
{
"resource": {
"resourceType": "MedicationRequest",
"id": "b7c8d9e0-f1a2-3456-bcde-789012345678",
"status": "unknown",
"intent": "order",
"medicationCodeableConcept": {
"coding": [
{
"system": "http://hl7.org/fhir/sid/ndc",
"code": "12345-6789-01",
"display": "Medication Name 20mg"
}
]
},
"subject": {
"reference": "Patient/c1d2e3f4-5678-90ab-cdef-1234567890ab"
},
"authoredOn": "2023-01-15",
"supportingInformation": [
{
"reference": "ExplanationOfBenefit/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
],
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/derivation-reference",
"extension": [
{
"url": "reference",
"valueReference": {
"reference": "ExplanationOfBenefit/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
}
]
}
]
}
}
]
}
#Conditions
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:
- Classifies the condition as Chronic, Not Chronic, or Unknown using the Chronic Condition Indicator Refined (CCIR) dataset
- 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).
Before
{
"resourceType": "Condition",
"code": {
"coding": [
{
"system": "http://hl7.org/fhir/sid/icd-10-cm",
"code": "E11.9",
"display": "Type 2 diabetes mellitus without complications"
}
]
}
}
After
{
"resourceType": "Condition",
"code": {
"coding": [
{
"system": "http://hl7.org/fhir/sid/icd-10-cm",
"code": "E11.9",
"display": "Type 2 diabetes mellitus without complications"
},
{
"system": "https://hcup-us.ahrq.gov/toolssoftware/ccsr/ccs_refined.jsp",
"code": "END002",
"display": "Diabetes mellitus without complication"
},
{
"system": "https://hcup-us.ahrq.gov/toolssoftware/ccsr/ccs_refined.jsp",
"code": "END005",
"display": "Diabetes mellitus, Type 2"
}
]
},
"category": [
{
"coding": [
{
"system": "https://hcup-us.ahrq.gov/toolssoftware/ccsr/ccs_refined.jsp",
"code": "END",
"display": "Endocrine, Nutritional and Metabolic Diseases"
}
],
"text": "Endocrine, Nutritional and Metabolic Diseases"
}
],
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/condition-related",
"valueCoding": {
"system": "https://api.flexpa.com/fhir/StructureDefinition/condition-chronicity",
"code": "C",
"display": "Chronic"
}
}
]
}
#Validation
The Validation transform uses the FHIR $validate operation to validate incoming resources and automatically fix common issues in a non-destructive way. Flexpa automatically:
- Validates resources ingested by our pipeline
- 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
- $validate Operation: Each incoming Bundle is sent to the FHIR
$validate endpoint.
- Parse OperationOutcome: The resulting
OperationOutcome is inspected for structural error issues.
- Auto-correction: Common issues are fixed non-destructively (e.g., convert scalars to arrays).
- Add
data-absent-reason: Missing required fields are annotated with the standard data-absent-reason extension and a value of unknown
Before Validation
{
"resourceType": "ExplanationOfBenefit",
"id": "example-id",
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/claim-type",
"code": "pharmacy"
}
]
}
// Missing required provider field
}
After Validation
{
"resourceType": "ExplanationOfBenefit",
"id": "example-id",
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/claim-type",
"code": "pharmacy"
}
]
},
"provider": {
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/data-absent-reason",
"valueCode": "unknown"
}
]
}
}
#Provider Directory
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.
GEThttps://api.flexpa.com/fhir/Practitioner
Individual healthcare providers can be accessed through the Practitioner resource. Each provider is identified by their National Provider Identifier (NPI) and includes details about their credentials, contact information, and practice locations.
Request parameters
- _projectstring
Static value 01956cb0-e18e-747a-8dba-265e83e1ade2 to search provider directory. Excluding this parameter will also return patient-specific records.
- namestring
Search by provider name (first, last, or full name)
- identifiertoken
Search by NPI (e.g., identifier=http://hl7.org/fhir/sid/us-npi|1234567890)
- addressstring
Search by address components (city, state, postal code)
Flexpa supports all Practitioner SearchParameters defined in the FHIR R4 specification, including active, email, family, given, phone, telecom, and more.
Request
GET
/fhir/Practitioner?identifier=[npi]&_project=01956cb0-e18e-747a-8dba-265e83e1ade2APP_TOKEN=your-application-access-token
curl "https://api.flexpa.com/fhir/Practitioner?identifier=http://hl7.org/fhir/sid/us-npi|1234567890&_project=01956cb0-e18e-747a-8dba-265e83e1ade2" \
-H "Authorization: Bearer $APP_TOKEN"
Response
{
"resourceType": "Bundle",
"type": "searchset",
"entry": [
{
"resource": {
"resourceType": "Practitioner",
"id": "1234567890",
"identifier": [
{
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "1234567890"
}
],
"name": [
{
"family": "Smith",
"given": ["John", "A"],
"prefix": ["Dr."]
}
],
"telecom": [
{
"system": "phone",
"value": "555-123-4567",
"use": "work"
}
],
"address": [
{
"line": ["123 Main St"],
"city": "San Francisco",
"state": "CA",
"postalCode": "94105",
"country": "US"
}
],
"gender": "male",
"qualification": [
{
"code": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v2-0360",
"code": "MD",
"display": "Doctor of Medicine"
}
]
}
}
]
}
}
]
}
GEThttps://api.flexpa.com/fhir/Organization
Healthcare organizations such as hospitals, clinics, and group practices can be accessed through the Organization resource. Each organization is identified by their National Provider Identifier (NPI) and includes details about their type, contact information, and locations.
Request parameters
- _projectstring
Static value 01956cb0-e18e-747a-8dba-265e83e1ade2 to search provider directory. Excluding this parameter will also return patient-specific records.
- namestring
Search by organization name
- identifiertoken
Search by NPI (e.g., identifier=http://hl7.org/fhir/sid/us-npi|1234567890)
- addressstring
Search by address components (city, state, postal code)
Flexpa supports all Organization SearchParameters defined in the FHIR R4 specification, including active, address-city, address-state, address-postalcode, email, phone, and more.
Request
GET
/fhir/Organization?identifier=[npi]&_project=01956cb0-e18e-747a-8dba-265e83e1ade2APP_TOKEN=your-application-access-token
curl "https://api.flexpa.com/fhir/Organization?identifier=http://hl7.org/fhir/sid/us-npi|2345678901&_project=01956cb0-e18e-747a-8dba-265e83e1ade2" \
-H "Authorization: Bearer $APP_TOKEN"
Response
{
"resourceType": "Bundle",
"type": "searchset",
"entry": [
{
"resource": {
"resourceType": "Organization",
"id": "2345678901",
"identifier": [
{
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "2345678901"
}
],
"active": true,
"type": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/organization-type",
"code": "prov",
"display": "Healthcare Provider"
}
]
}
],
"name": "Bay Area Medical Center",
"telecom": [
{
"system": "phone",
"value": "555-987-6543",
"use": "work"
},
{
"system": "email",
"value": "contact@bayareamedical.example.com",
"use": "work"
}
],
"address": [
{
"line": ["456 Healthcare Blvd"],
"city": "San Francisco",
"state": "CA",
"postalCode": "94107",
"country": "US"
}
]
}
}
]
}
#FAQ
#Which FHIR version does the API support?
The API supports FHIR R4.
#Does the API support CORS?
No, the API does not support CORS.
The Quickstart repository contains a simple example of a server making requests - replicating that behavior for both the Link operations but also subsequent FHIR requests is important for security.
POSThttps://api.flexpa.com/apply
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.
Parameters
- namestringRequired
Your name
- emailstringRequired
Your email address
- whystringRequired
Why do you want to work at Flexpa?
- locationstringRequired
Your location
- resumestringRequired
A link to your resume
- phonestring
A phone number where we can reach you
- githubstring
A link to your GitHub profile
- linkedinstring
A link to your LinkedIn profile
- websitestring
A link to your personal website
- twitterstring
A link to your Twitter profile
curl -X POST https://api.flexpa.com/apply \
-H 'Content-Type: application/json' \
-d '{
"name": "Fizz Buzz",
"email": "fizz@example.com",
"why": "I want to work at Flexpa because...",
"location": "Foobar, USA",
"resume": "https://www.dropbox.com/s/123456789/resume.pdf",
"phone": "555-555-5555",
"github": "@fizzbuzz",
"linkedin": "https://www.linkedin.com/in/fizz-buzz-123456789/",
"website": "https://www.example.com/",
"twitter": "@fizzbuzz"
}'
#Next steps