FHIR API Reference

#Records

The Flexpa FHIR API is a secure, standards-based REST API 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 Link 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 FHIR 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

Getting started?

Quickstart

Get started with a cloneable quickstart project

Try it out →

Looking for a demo?

MyFlexpa

Go through a Patient Access API flow yourself! See exactly what patients will see

Try out MyFlexpa →

#API Keys

The Flexpa API uses a two-layer authentication system. API Keys are used for secuerly identifying your application to Flexpa in Flexpa Link and in Link API endpoints.

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 Flexpa Link setup.

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 Token Endpoint 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 Link 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 via Flexpa Link
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 Patient Authorization 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.
iss: Identifies the issuer of the JWT. Always "https://api.flexpa.com/".
aud: Identifies the intended audience of the JWT. Always "https://api.flexpa.com/".

#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.
iss: Identifies the issuer of the JWT. Always "https://api.flexpa.com/".
aud: Identifies the intended audience of the JWT. Always "https://api.flexpa.com/".

#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 Flexpa Link 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.

#Link API

In order to link and manage patient authorizations in your application, you will first need to interact with the Flexpa Link API. Link API routes begin with the /link/ subpath of the URL.

The Flexpa Link component must be configured as a prerequisite before using the Link API.

POSThttps://api.flexpa.com/link/exchange

#Exchange

It's important to only call this endpoint from your server, as to not expose your secret_key

Request fields

public_tokenstringRequired: Received from the Flexpa Link onSuccess callback
secret_keystringRequired: Your Flexpa API secret key

Response fields

access_tokenstring: The access_token to be used to make FHIR Requests on behalf of this user.
expires_innumber: expires_in is the time (in seconds) for which the access_token is valid. Defaults to 86400 seconds (24 hours).; For ONE_TIME usage patient authorizations, once this time has elapsed, data that was synced is deleted from Flexpa's data cache.
usageenum: usage is the resolution of intended data usage and the capabilities of the selected endpoint. If the usage indicated in FlexpaLink.create() was MULTIPLE but the endpoint does not support refreshable authorization then we will return ONE_TIME here as an indication.
MULTIPLEstring: Returned when both the intended usage was MULTIPLE and the selected endpoint is refreshable
ONE_TIMEstring: Returned when the intended usage is ONE_TIME or the endpoint is not refreshable
refresh_tokenstring: Only provided for MULTIPLE usage patient authorizations. The refresh_token to be used to obtain a new access_token once the current one expires using the token refresh route.
refresh_expires_innumber: refresh_expires_in is the time (in seconds) for which the access_token is refreshable. Once this time has elapsed, the user is required to re-authorize. A null suggests that this value is either unknown or not applicable. A 0 indicates an indefinite expiration.; For MULTIPLE usage patient authorizations, the refresh_token is valid for 7776000 seconds (90 days) by default. Once this time has elapsed, data that was synced is deleted from Flexpa's data cache.
patientstring: The Patient ID connected to the authorization (formatted as a FHIR Resource Path Patient/<patient_id>).
userobject: Information about the end user you can specify during the create step of Flexpa Link. Echoed back to you in this response.
externalIdstring: A unique identifier of the user as that is owned by the host application.
endpointobject: The endpoint to be used to make FHIR Requests on behalf of this user.
syncobject: An object containing information about the sync job of the patient authorization.
resourceTypesobject: A summary of the resource types that Flexpa successfully synced for the patient authorization. Synced data is available for querying via the FHIR API. The keys are the resource types and the values are the number of resources synced of that type.; Flexpa's supported resource types will always appear in this object, even if no resources of that type were synced; the count will equal 0 in this case. All other FHIR resource types will only appear in this object if resources of that type were synced.
lastSyncedAtobject: The last time this patient's data was successfully synced in Unix time (in seconds). This property specifically refers to the timestamp of the last COMPLETED sync job.
stateobject: The state of the current sync job associated with this patient authorization. See the sync job states section for more information.
timeUntilMaxAuthnumber | string: The time until the patient authorization reaches its maximum authorization period. When a number, it represents seconds until the maximum authorization period is reached. When a string, it can be one of the following values:
'unknown'string: The maximum authorization period is unknown.
'indefinite'string: The authorization does not have a maximum period and will not expire.
'unsupported'string: The endpoint does not support refreshable authorizations or the authorization type is not compatible.; After the maximum authorization period is reached, the patient will need to re-authorize to continue accessing their data. This is particularly relevant for MULTIPLE usage patient authorizations.

Request

POST

/link/exchange

curl -X POST https://api.flexpa.com/link/exchange \
  -H 'Content-Type: application/json' \
  -d '{
    "public_token": "public_token_950fae5f-...",
    "secret_key": "<your-secret-key>"
  }'

Response

{
  "access_token": "eyJhbGciOiJFUzI1NiJ9.eyJqdGkiOiI5NmQ5Njgw...",
  "expires_in": 86400,
  "usage": "ONE_TIME",
  "refresh_expires_in": 86400,
  "patient": "Patient/33512af4-5ab2-4be2-90f5-3945cff01c1a",
  "user": {
    "externalId": "1234567890"
  },
  "endpoint": {
    "id": "d39433b7-0fbd-4bc2-bdae-fb276799979f",
    "label": ["Humana"],
    "name": "humana-sandbox",
    "refreshable": true
  },
  "timeUntilMaxAuth": 7890000
}

GEThttps://api.flexpa.com/link/introspect

#Introspect

When using the introspect endpoint, we will return an additional endpoint field containing information about the health plan used to create the access token.

Request headers

AuthorizationstringRequired: An Authorization: Bearer header value must presented with a Patient Access Token

Response fields

jtistring: A random nonce value that uniquely identifies the access token.
iatnumber: When the access token was issued in Unix time (in seconds).
expnumber: When the access token expires in Unix time (in seconds).
activeboolean: A boolean that states whether the access token can be used.
issnumber: The issuer of the access token. Always https://api.flexpa.com.
audnumber: The audience of the access token. Always https://api.flexpa.com.
substring: A unique identifier for the patient authorization backing this access token.
patientstring: The Patient ID connected to the authorization (formatted as a FHIR Resource Path Patient/<patient_id>).
client_idstring: The ID of the application that created this patient authorization.
userobject: Information about the end user you can specify during the create step of Flexpa Link. Echoed back to you in this response.
externalIdstring: A unique identifier of the user as that is owned by the host application.
stateenum: The state indicates where the token is in the authorization flow. See the Authorization states for more information.
usageenum: usage is the resolution of intended data usage and the capabilities of the selected endpoint. If the usage indicated in FlexpaLink.create() was MULTIPLE but the endpoint does not support refreshable authorization then we will return ONE_TIME here as an indication.
MULTIPLEstring: Returned when both the intended usage was MULTIPLE and the selected endpoint is refreshable
ONE_TIMEstring: Returned when the indented usage is ONE_TIME or the endpoint is not refreshable
endpointobject: The Endpoint to which the patient authorized access to, can be used to determine which health plan the patient connected.
syncobject: An object containing information about the sync job of the patient authorization.
resourceTypesobject: A summary of the resource types accessible via Flexpa for the patient authorization. Synced data is available for querying via the FHIR API. The keys are the resource types and the values are the number of resources synced of that type.; Flexpa's supported resource types will always appear in this object, even if no resources of that type were synced; the count will equal 0 in this case. All other FHIR resource types will only appear in this object if resources of that type were synced.
lastSyncedAtobject: The last time this patient's data was successfully synced in Unix time (in seconds). This property specifically refers to the timestamp of the last COMPLETED sync job.
stateobject: The state of the current sync job associated with this patient authorization. See the sync job states section for more information.
timeUntilMaxAuthnumber | string: The time until the patient authorization reaches its maximum authorization period. When a number, it represents seconds until the maximum authorization period is reached. When a string, it can be one of the following values:
'unknown'string: The maximum authorization period is unknown.
'indefinite'string: The authorization does not have a maximum period and will not expire.
'unsupported'string: The endpoint does not support refreshable authorizations or the authorization type is not compatible.; After the maximum authorization period is reached, the patient will need to re-authorize to continue accessing their data. This is particularly relevant for MULTIPLE usage patient authorizations.

Request

GET

/link/introspect

ACCESS_TOKEN=flexpa-link-access-token

curl https://api.flexpa.com/link/introspect \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response

{
  "jti": "4e99f5ae-eb40-4161-9506-23b119e7136f",
  "iat": 1671116375,
  "exp": 1671202775,
  "active": true,
  "iss": "https://api.flexpa.com",
  "aud": "https://api.flexpa.com",
  "sub": "329034ef-5fa8-4a08-99d5-c389e22a2533",
  "patient": "Patient/33512af4-5ab2-4be2-90f5-3945cff01c1a",
  "client_id": "46db2b53-1291-4e44-9d75-e4a26ceb1fa7",
  "user": {
    "externalId": "1234567890"
  },
  "state": "EXCHANGED",
  "usage": "MULTIPLE",
  "endpoint": {
    "id": "d39433b7-0fbd-4bc2-bdae-fb276799979f",
    "label": ["Humana"],
    "name": "humana-sandbox",
    "refreshable": true
  },
  "sync": {
    "resourceTypes": {
      "Coverage": 18,
      "ExplanationOfBenefit": 11,
    },
    "state": "COMPLETED",
    "lastSyncedAt": 1712163905
  },
  "timeUntilMaxAuth": 7890000
}

POSThttps://api.flexpa.com/link/token

#Token Endpoint

The token endpoint supports two grant types:

client_credentials - For obtaining Application Access Tokens
refresh_token - For refreshing Patient Access Tokens with MULTIPLE usage

Request headers

AuthorizationstringRequired: To authenticate, include an Authorization: Basic header with your Flexpa API keys obtained from Flexpa Portal. Concatenate your publishable key and secret key with a colon (:), then encode this string in base64 format.; The header format should look like this: Authorization: Basic base64_encoded_credentials.

Request body

grant_typestringRequired: The type of grant used to obtain the access token.; Valid values:; client_credentials - For Application Access Tokens

refresh_token - For refreshing Patient Access Tokens
refresh_tokenstring: Required when grant_type is refresh_token.; The refresh_token obtained from the exchange endpoint. Once you have used this token to refresh the access_token, it is no longer valid.; A new refresh_token will be issued upon successful token refresh.

When using grant_type=refresh_token, this endpoint only supports MULTIPLE usage patient authorizations. See patient authorization usage for more information.

When using grant_type=client_credentials, you must use live mode API keys. Application access tokens cannot be created using test mode keys.

For more details on obtaining Application Access Tokens, see the Application Access Tokens section.

Response fields

access_tokenstring: The access_token to be used to make Flexpa API requests.; For Patient Access Tokens, this is associated with a specific patient. For Application Access Tokens, this is associated with your application only.
expires_innumber: expires_in is the time (in seconds) for which the access_token is valid.; For Patient Access Tokens: 86400 seconds (24 hours). For Application Access Tokens: 1800 seconds (30 minutes).
token_typestring: The type of token, always Bearer.
refresh_tokenstring: Only returned for grant_type=refresh_token.; The new refresh_token to be used to refresh the Patient Access Token.
refresh_expires_innumber: Only returned for grant_type=refresh_token.; The time period for which the refresh_token is valid. You must call this route to refresh the Patient Access Token before this time period elapses otherwise, the patient will need to re-authorize.; Defaults to 7776000 seconds (90 days).
syncobject: Only returned for grant_type=refresh_token.; An object containing information about the sync job of the patient authorization.
resourceTypesobject: A summary of the resource types that Flexpa successfully synced for the patient authorization. Synced data is available for querying via the FHIR API. The keys are the resource types and the values are the number of resources synced of that type.; Flexpa's supported resource types will always appear in this object, even if no resources of that type were synced; the count will equal 0 in this case. All other FHIR resource types will only appear in this object if resources of that type were synced.
lastSyncedAtnumber | null: The last time this patient's data was successfully synced in Unix time (in seconds). This property specifically refers to the timestamp of the last COMPLETED sync job.
stateobject: The state of the current sync job associated with this patient authorization. See the sync job states section for more information.
timeUntilMaxAuthnumber | string: Only returned for grant_type=refresh_token.; The time until the patient authorization reaches its maximum authorization period. When a number, it represents seconds until the maximum authorization period is reached. When a string, it can be one of the following values:
'unknown'string: The maximum authorization period is unknown.
'indefinite'string: The authorization does not have a maximum period and will not expire.
'unsupported'string: The endpoint does not support refreshable authorizations or the authorization type is not compatible.; After the maximum authorization period is reached, the patient will need to re-authorize to continue accessing their data. This is particularly relevant for MULTIPLE usage patient authorizations.
usagestring: Only returned for grant_type=refresh_token.; The usage mode of the patient authorization. Can be either ONE_TIME or MULTIPLE. This parameter indicates whether the authorization is a one-time access or allows for multiple refreshes. See patient authorization usage for more information.

Errors

invalid_client: The client credentials are invalid. Ensure your API keys are correctly base64 encoded and passed in the Authorization header.
invalid_grant: The refresh token provided was invalid or expired. Verify that the refresh token is correct and hasn't been used previously.
server_error: An unexpected error occurred. Please try again later. If the problem persists, contact support.

Refresh Token Grant Request

POST

/link/token

PUBLIC_KEY=pk_test...
SECRET_KEY=sk_test...
REFRESH_TOKEN=flexpa-link-refresh-token

# Base64 encode the credentials
CREDENTIALS=$(echo -n "${PUBLIC_KEY}:${SECRET_KEY}" | base64)

curl -X POST https://api.flexpa.com/link/token \
  -H "Authorization: Basic ${CREDENTIALS}" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "'"${REFRESH_TOKEN}"'"
  }'

Client Credentials Grant Request

POST

/link/token

PUBLIC_KEY=pk_test...
SECRET_KEY=sk_test...

# Base64 encode the credentials
CREDENTIALS=$(echo -n "${PUBLIC_KEY}:${SECRET_KEY}" | base64)

curl -X POST https://api.flexpa.com/link/token \
  -H "Authorization: Basic ${CREDENTIALS}" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials"
  }'

Reponse

{
  "access_token": "eyJhbGciOiJFUzI1NiJ9.eyJqdGkiOiI5NmQ5Njgw...",
  "expires_in": 86400,
  "token_type": "Bearer",
  "refresh_token": "b3500e631567d140ff6b5efa241c8359548e81d2...",
  "refresh_expires_in": 7776000,
  "usage": "MULTIPLE",
  "sync": {
    "resourceTypes": {
      "AllergyIntolerance": 3,
      "CarePlan": 21,
      "CareTeam": 10,
      "Condition": 9,
      "Coverage": 18,
      "Device": 0,
      "DiagnosticReport": 0,
      "DocumentReference": 1,
      "Encounter": 0,
      "ExplanationOfBenefit": 11,
      "Goal": 16,
      "Immunization": 0,
      "MedicationDispense": 0,
      "MedicationRequest": 3,
      "Observation": 7,
      "Patient": 1,
      "Procedure": 62,
      "Provenance": 0,
      "Location": 0,
      "Medication": 0,
      "Organization": 0,
      "Practitioner": 3,
      "PractitionerRole": 0
    },
    "state": "COMPLETED",
    "lastSyncedAt": 1712163905
  },
  "timeUntilMaxAuth": 5184000
}

POSThttps://api.flexpa.com/link/revoke

#Revoke

If a patient has linked multiple times to the same endpoint from the same application, /link/revoke only needs to be called once to revoke all authorizations. Revoking an authorization will expunge the patient's data from Flexpa's cache and invalidate the access_token and refresh_token.

Request headers

AuthorizationstringRequired: An Authorization: Bearer header value must presented with a Patient Access Token

Request fields

secret_keystringRequired: Your Flexpa API secret key

Response fields

countnumber: The number of access tokens revoked

Request

POST

/link/revoke

ACCESS_TOKEN=flexpa-link-access-token

curl -X POST https://api.flexpa.com/link/revoke \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "secret_key": "sk_test..."
  }'

Response

{
  "count": 1
}

#Sync Job States

When a patient authorizes access to their health data through Flexpa Link, 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 FHIR 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)
- 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

Intro to FHIR

FHIR, or Fast Healthcare Interoperability Resources, is a standard for exchanging healthcare information electronically

Read introduction →

FHIR R4 Standard

Flexpa implements the FHIR R4 specification, the industry standard for healthcare interoperability

View FHIR R4 Documentation →

GEThttps://api.flexpa.com/fhir/[Resource]/:id

#Read

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 headers

AuthorizationstringRequired: An Authorization: Bearer header value must presented with a Patient Access Token or an Application Access Token

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 payer for the requested Patient. Please re-authorize or reach out to support.

Request

GET

/fhir/[Resource]

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]

#Search

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 headers

AuthorizationstringRequired: An Authorization: Bearer header value must presented with a Patient Access Token or an Application Access Token

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.

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 payer for the requested Patient. Please refresh again or reach out to support.

Request

GET

/fhir/[Resource]

const ACCESS_TOKEN="flexpa-link-access-token"

const searchUrl = "https://api.flexpa.com/fhir/ExplanationOfBenefit";

const response = await fetch(searchUrl, {
  headers: {
    "authorization": `Bearer ${ACCESS_TOKEN}`,
  },
});

const searchBundle = await response.json();

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

#Patient $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.

Request headers

AuthorizationstringRequired: An Authorization: Bearer header value must be presented with a Patient Access Token when using a wildcard $PATIENT_ID or otherwise an Application Access Token

Response fields

ResponseBundle: Patient $everything returns a Bundle that contains all resources that reference the Patient resource.

Request

GET

/fhir/Patient/$PATIENT_ID/$everything

ACCESS_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", ...} },
  ]
}

This example makes use of the $PATIENT_ID wildcard parameter which requires a Patient Access Token. When using with an Application Access Token, replace the wildcard parameter with a specific Patient ID.

POSThttps://api.flexpa.com/fhir/Patient/:patientId/$expunge

#Patient $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.

Request

POST

/fhir/Patient/$PATIENT_ID/$expunge

ACCESS_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"
        }
      ]
    }
  ]
}

GEThttps://api.flexpa.com/fhir/metadata

#Capability Statement

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.

https://api.flexpa.com/fhir/metadata is an unauthenticated route. You do not need to provide an access_token to access this route.

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

Request

GET

/fhir/metadata

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:

_totalstring

The _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 response
accurate: 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.

_sortstring

The _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.

_summarystring

The _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.

_elementsstring

The _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.

_countstring

The _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": [...]
}

#Pagination

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

Request

GET

/fhir/Condition?_count=3

ACCESS_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
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.

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

GET

/fhir/[Resource]/:id

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"
  }],
};

#Transforms

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:

Tags
Identifiers
References
NPIs
Validation

#Tags

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:

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/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/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"
                }
              }
            ]
          }
        ]
      }
    }
  ]
}

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

NPPES Registry

The National Plan and Provider Enumeration System is the authoritative registry for healthcare provider information in the United States

Visit NPPES Website →

GEThttps://api.flexpa.com/fhir/Practitioner

#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 headers

AuthorizationstringRequired: An Authorization: Bearer header value must be presented with an Application Access Token

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-265e83e1ade2

APP_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

#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 headers

AuthorizationstringRequired: An Authorization: Bearer header value must be presented with an Application Access Token

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-265e83e1ade2

APP_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

#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

Request

POST

/apply

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

Quickstart

Get started with a cloneable quickstart project

Try it out →

Consent

Flexpa Link is a client-side component to help your users link health plan data sources

Build with Flexpa Link →