Flexpa
Developer PortalFeedbackContact usOnboard

All docs

Records

  • How it works
  • What you need
  • API Keys
  • Access Tokens
  • Patient Access Token
  • Application Access Token
  • Patient Authorizations
  • Request ID

Link API

  • Exchange
  • Introspect
  • Token Endpoint
  • Revoke
  • Sync Job States

FHIR API

  • Read
  • Search
  • Patient $everything
  • Patient $expunge
  • Capability Statement
  • Wildcard Parameters
  • Search Result Parameters
  • Pagination
  • Referenced Resources
  • Errors

Transforms

  • Tags
  • Identifiers
  • References
  • NPIs
  • Medications
  • Validation

Provider Directory

  • Practitioner
  • Organization

FAQ

  • Apply

Next steps

    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

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

    #What you need

    To use the Flexpa 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.

    Flexpa API

    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 dataPatient Access Token
    Make application-level API calls without patient contextApplication Access Token
    Access API endpoints like /fhir/metadataEither 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:

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

    Patient Authorizations can be configured as either:

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

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

    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:

    1. client_credentials - For obtaining Application Access Tokens
    2. 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.

    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 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:

    • Location
    • Device
    • PractitionerRole

    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:

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

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

    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:

    1. Patient Authorization ID: Unique identifier of the patient authorization that sourced this data
    2. Endpoint ID: Identifier of the health plan or provider endpoint that supplied the data
    3. Application ID: Your application's identifier within the Flexpa system
    4. Patient Authorization Mode: Whether the authorization was in TEST or LIVE mode
    5. 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:

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

    #Benefits

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

    #How It Works

    The Identifiers transform uses UUIDv5 to deterministically generate UUIDs. The input for the UUID is formed by concatenating 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:

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

    #Benefits

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

    #How It Works

    The References transform operates in multiple stages.

    First, during the Identifiers transform, all references within resources are updated to use the new UUIDv5 IDs Second, during the NPI transform, identifiers with NPIs are expanded into full references to Provider resources Finally, during sourcing, fullUrl and source metadata are added to preserve origin information

    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:

    1. Identifies NPIs within the bundle
    2. Looks up detailed provider information from those NPIs using the National Plan & Provider Enumeration System (NPPES)
    3. Expands NPI references in the bundle to include full provider details
    4. 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:

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

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

    #Safety Notice

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

    #Benefits

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

    #How It Works

    The Medications transform occurs automatically during data processing and includes:

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

    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:

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

    #Benefits

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

    #How it works

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

    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 →
    Status TwitterGitHub

    © 2025 Flexpa. All rights reserved.