Flexpa
Developer PortalContact us

Flexpa overview

  • Introduction
  • Patient access
  • Use cases
  • What we don't do
  • Pricing

Getting started

  • Quickstart
  • Test mode
  • Going live
  • Changelog
  • FAQ

Network

  • Payers
  • Endpoints

Tools

  • Flexpa Link
  • Flexpa API
    • URL
    • Authentication
    • Request ID
    • FHIR Resources
    • Open APIs
    • FAQ
    • Next steps
  • Data analytics
  • Connections
  • MyFlexpa
  • Portal
  • Scan

FHIR Overview

  • Introduction
  • Reading resources
  • Searching resources
  • Code systems

Patient Guides

  • Steps to connect
  • Troubleshooting tips

About Flexpa

  • Flexpa OS
  • Brand kit
  • Join us
  • Support

API reference

The Flexpa API is a REST API. Our API functions as an opinionated request proxy layer for FHIR: every resource available in the API conforms to one available in FHIR.

To start using Flexpa API, your users must connect their health plan with Flexpa Link.

You can use the Flexpa API in test mode, which doesn't use real patient data. The API key you use to authenticate the request determines whether the request is made in live mode or test mode.

Questions? Email support →

#URL

The base URL for the Flexpa API is https://api.flexpa.com. All API requests must be made with the https:// protocol. Calls made over plain-text http:// will fail.

#Authentication

The Flexpa API uses API keys and Access Tokens to authenticate requests. You obtain an Access Token as the last step of the Flexpa Link auth flow.

Authentication to the per-patient FHIR Resources is performed via bearer auth.

Submit an Authorization header with a value of Bearer ${PAT} where ${PAT} is a currently valid Access Token.

#Access Tokens

Patient Access Tokens are obtained by exchanging a Flexpa Link public_token for an API access_token. Flexpa Link returns a public_token in the onSuccess callback after a user has successfully connected their health plan.

Patient Access Tokens are string-encoded JSON Web Tokens (JWTs).

JSON Web Tokens can be decoded to inspect their contents. You can decode a JWT in two ways:

  • Calling the introspect endpoint
  • Using a client-side library like jwt-decode

The Flexpa API does not support client side requests. Read more about making server side requests here.


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


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 parameters

public_tokenRequired
string

Received from the Flexpa Link onSuccess callback

secret_keyRequired
string

Your Flexpa API secret key

Response object

access_token
string

The access_token to be used to make FHIR Requests on behalf of this user

expires_in
number

expires_in is the time period for which the access_token is valid. Once this time has elapsed, your application will be required to refresh the access_token

refresh_expires_in
number

refresh_expires_in is the time period 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.

endpoint
object

The endpoint to be used to make FHIR Requests on behalf of this user

Request

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

Response

{
  "access_token": "eyJhbGciOiJFUzI1NiJ9.eyJqdGkiOiI5NmQ5Njgw...",
  "expires_in": 3600,
  "refresh_expires_in": 86400,
  "endpoint": {
    "id": "d39433b7-0fbd-4bc2-bdae-fb276799979f",
    "label": ["Humana"],
    "name": "humana-sandbox",
    "refreshable": true,
    "resources": [
      "Coverage",
      "ExplanationOfBenefit",
      "Patient"
    ]
  }
}

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.

Parameters

AuthorizationRequired
string

An Authorization: Bearer header value must presented with the access_token obtained from the link exchange endpoint

Response object

jti
string

The unique identifier for the patient authorization backing this access token

iat
number

When the access token was issued in UNIX epoch time

sub
string

Also known as the "subject", this value is the patient ID connected to the authorization (formatted as a FHIR Resource Path Patient/<patient_id>)

exp
number

When the access token expires in UNIX epoch time

state
enum

The state is an enumerated list of values:

  • CREATED
    A PAT is CREATED immediately when Flexpa Link is opened
  • REDIRECTED
    A PAT is REDIRECTED when a patient has been redirected to the payer's authorization screen
  • AUTHORIZED
    A patient has successfully completed an authorization, but the Link exchange step has not yet been completed
  • EXCHANGED
    The Link exchange step has been completed and the PAT is expected to be fully usable
  • REVOKED
    The patient has chosen to revoke access to the PAT and it is no longer usable
  • REFRESHED
    The PAT has been refreshed using /link/refresh and is no longer usable
  • ERRORED
    Authorization was not sucessful and resulted in an error
  • ABANDONED
    Authorization did not end in an error but was not completed
  • BOUNCED
    A PAT is BOUNCED when a patient exits Link without interacting with the interface
endpoint
object

The Endpoint to which the patient authorized access to, can be used to determine which health plan the patient connected

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,
  "sub": "Patient/74532b683658335246434e495a53425462476c5741673d3d",
  "exp": 1671119975,
  "state": "EXCHANGED",
  "endpoint": {
    "id": "d39433b7-0fbd-4bc2-bdae-fb276799979f",
    "label": ["Humana"],
    "name": "humana-sandbox",
    "refreshable": true,
    "resources": [
      "Coverage",
      "ExplanationOfBenefit",
      "Patient"
    ]
  }
}

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

#Refresh

Flexpa attempts to obtain a long-lived authorization for every patient link. When a long-lived authorization is obtained, expired access tokens can be refreshed or exchanged for a new, valid one.

Parameters

secret_keyRequired
string

Your Flexpa API secret key

access_tokenRequired
string

The access_token you are attempting to refresh. The access_token must be in the EXCHANGED state to be refreshable. To get the current state of an access_token, use the Introspect API.

Once refreshed, this access_token becomes invalidated and cannot be used for future requests, including refresh requests. For future requests, use the access_token that is included in the response object (below).

Response object

access_token
string

The access_token to be used to make Flexpa API requests on behalf of this user

expires_in
number

expires_in is the time period for which the access_token is valid. Once this time has elapsed, your application will be required to refresh the access_token once more

refresh_expires_in
number

refresh_expires_in is the time period 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.

Errors

NO_USABLE_PAT
No Patient Access Token could be found matching your request
NO_REFRESH_TOKEN
This Patient Access Token is not refreshable
INVALID_ENDPOINT
Flexpa no longer supports the payer for which the access token was originally issued
REFRESH_ERROR
An error occurred during the refresh exchange
NOT_PERMITTED
Your application does not own this access token

Request

POST
/link/refresh
curl -X POST https://api.flexpa.com/link/refresh \
  -H 'Content-Type: application/json' \
  -d '{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "secret_key": "sk_test..."
  }'

Response

{
  "access_token": "eyJhbGciOiJFUzI1NiJ9.eyJqdGkiOiI5NmQ5Njgw...",
  "expires_in": 3600,
  "refresh_expires_in": 86400,
  "endpoint": {
    "id": "d39433b7-0fbd-4bc2-bdae-fb276799979f",
    "label": ["Humana"],
    "name": "humana-sandbox",
    "refreshable": true,
    "resources": [
      "Coverage",
      "ExplanationOfBenefit",
      "Patient"
    ]
  }
}

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.

Headers

AuthorizationRequired
string

An Authorization: Bearer header value must presented with the access_token obtained from the link exchange endpoint

Parameters

secret_keyRequired
string

Your Flexpa API secret key

Response object

count
number

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
}

#FHIR Resources

You can make FHIR Resource requests after acquiring an access_token from POST /link/exchange.

The Flexpa API currently supports Read and Search requests. Identify the FHIR Resource you want to Read or Search after the /fhir/ subpath of the URL.


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.

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

Parameters

AuthorizationRequired
string

An Authorization: Bearer header value must presented with the access_token obtained from the link exchange endpoint

patient
string

The ID of the patient for whom you are making a search. We recommend using this parameter along with the patient ID wildcard parameter

Response object

resourceType
string

Searches return a Bundle resource type

entry
array

An array of FHIR resources expected to match the resource type of the search

For a full list of response object properties, please refer to the FHIR Resources documentation.

Request

GET
/fhir/[Resource]
ACCESS_TOKEN=flexpa-link-access-token

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

Response

{
  "resourceType": "Bundle",
  "id": "22f61d0877b54b2a8a2feb57bfe2c462",
  "entry": [{
    "resource": {
      "resourceType":"ExplanationOfBenefit",
      ...
    }
  }]
}

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.

Parameters

AuthorizationRequired
string

An Authorization: Bearer header value must presented with the access_token obtained from the link exchange endpoint

identifier
string

The identifier of the resource to be retrieved - used in the last part of the URL path segment

Response object

resourceType
string

Reads return an individual resource, so the resource type is expected to correspond to the resource you are reading

For a full list of response object properties, please refer to the FHIR Resources documentation.

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

#Wildcard parameters

We highly recommend that you use the $PATIENT_ID wildcard parameter in your API requests.

Flexpa API supports wildcard parameters that can be used in URL query parameters in FHIR Resources 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 value sourced from the access_token, id_token, or other locations when you make a request to Flexpa.

The $PATIENT_ID wildcard can be used directly in the pathname of the URL of a read or as the parameter patient or subject in a search request:

  • Read: https://api.flexpa.com/fhir/Patient/$PATIENT_ID
  • Search: https://api.flexpa.com/fhir/Coverage?patient=$PATIENT_ID

Wildcard in Coverage Search

ACCESS_TOKEN=flexpa-link-access-token

curl "https://api.flexpa.com/fhir/Coverage?patient=$PATIENT_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Wildcard in Patient Read

ACCESS_TOKEN=flexpa-link-access-token

curl "https://api.flexpa.com/fhir/Patient/$PATIENT_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

#Pagination

Some payers support 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 _count parameter in your search request.

Example: https://api.flexpa.com/fhir/Coverage?patient=$PATIENT_ID&_count=5

Payers may also automatically paginate search results with many records.

If a payer supports pagination, they provide a link object in the Bundle that references the next page of search results:

"link": [
  {
    "relation": "next",
    "url": "https://api.flexpa.com/fhir/ExplanationOfBenefit?_count=2&patient=74532b683658335246434e495a53425462476c5741673d3d&ct=er97f5lRTXS1Ukl%2BdmqekpWSdpCni1VdoFlUoaN%2FclVOYJllTlC5IwTY2ioHhVgZKocEOVsZKXsGh4FIV38rM1NTU0PlQGc3KwtltwBnK8d0r0pH51Cn5HRHV8cAozB3T8dQx8BIx8AMx3QnV0dHr0BXZ0ff3DIlHaWixLz0VCWraqXcTJDtSjpKuYkVSlZKBqbOhq4GSrW1sQAAAAD%2F%2Fw%3D%3D"
  },
  {
    "relation": "self",
    "url": "https://api.flexpa.com/fhir/ExplanationOfBenefit?_count=2&patient=74532b683658335246434e495a53425462476c5741673d3d"
  }
]

To access the next page of resources, make a GET request to the URL indicated by "relation": "next". Payers may also provide a "relation": "previous" property, which links to the previous results page.

Flexpa API updates the URLs in the link object returned from the payer. This allows you to quickly retrieve the related data like any other FHIR request through Flexpa API.


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

Reponse object

processing

Processing issues. This is expected to be final (e.g., there is no point resubmitting the same content unchanged).

not-supported
The interaction, operation, resource or profile is not supported.
forbidden
The user does not have the rights to perform this action.
exception
An unexpected internal error has occurred.

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

Error codes

processing

Processing issues. This is expected to be final (e.g., there is no point resubmitting the same content unchanged).

not-supported
The interaction, operation, resource or profile is not supported.
forbidden
The user does not have the rights to perform this action.
exception
An unexpected internal error has occurred.

Error response

{
  "resourceType": "OperationOutcome",
  "issue": [{
    "severity": "error",
    "code": "not-supported"
  }],
};

#Open APIs

Flexpa makes available some APIs to your application without authentication. These APIs are largely informational and intended to supplement equivalently accessible information found in our documentation.


GEThttps://api.flexpa.com/organizations

#Organizations

An organization is a payer, provider, or vendor entity that operates an Endpoint.

This API returns data also available in our payer network documentation.

The URL https://api.flexpa.com/payers was deprecated on August 9, 2023, after which https://api.flexpa.com/organizations replaced it.

Response object

name
string

The name of the organization

id
string

The id that Flexpa uses to identify this organization

note
string

The note is used to detail whether the organization supports just CMS plans or all plans (including commercial lives)

type
string

The type details whether the organization is a payer, a provider, a vendor, or another type of entity.

Request

GET
/organizations
curl https://api.flexpa.com/organizations \
  -H 'Content-Type: application/json'

Response

[
    {
        "name": "SCAN Health Plan",
        "id": "a4212073-f832-483c-8fd0-706f97fe3d8e",
        "note": "CMS plans",
        "type": "PAYER"
    },
    {
        "name": "Blue Cross and Blue Shield of North Carolina",
        "id": "12db2e9e-26f5-4ee6-b705-29ee9349f653",
        "note": "CMS plans",
        "type": "PAYER"
    },
    ...
]

GEThttps://api.flexpa.com/endpoints

#Endpoints

Endpoints are individual FHIR REST API servers in Flexpa's network created and maintained by payers. They are used to access patient data.

This API returns data also available our endpoint network documentation.

The payer endpoint property was deprecated on August 9, 2023, after which the organization property replaced it.

Response object

name
string

The name attribute is a human-readable unique identifier for the endpoint. This attribute is subject to change, so we recommend using the id attribute as a static identifier.

id
string

The id that Flexpa uses to identify this endpoint

mode
string

The mode is used to detail whether the endpoint is for test or live mode

label
array

The label is a human-readable name for the endpoint. This is often equivalent to the payer name, but may be a brand level name if the payer has multiple brands.

refreshable
boolean

The refreshable is boolean that indicates whether the endpoint is refreshable and supports off-line access.

refreshValidFor
number

The refreshValidFor represents the maximum time (in seconds) for which an access_token can be refreshed against the endpoint. After this period elapses, the user is required to re-authorize. A 0 indicates that the endpoint is refreshable indefinitely. If the endpoint is refreshable, a null suggests that this value is unknown to Flexpa. This value is also accessible as refresh_expires_in in the response body of exchange and refresh.

maxAuthPeriod
number

The maxAuthPeriod represents the maximum time (in seconds) for which an endpoint will allow a user to keep an application authorized to it. After this period elapses, the user is required to re-authorize. A 0 indicates that the endpoint can be authorized indefinitely. If the endpoint is refreshable, a null suggests that this value is unknown to Flexpa.

status
enum

The status is an enumerated list of values:

  • LIVE
    The endpoint is available for use, but has not yet been validated via our user testing program.
  • USER_VALIDATED
    The endpoint is live and has been validated by a user.
  • INFERRED_VALIDATED
    The endpoint is live and has been validated based on related tests.
  • BROKEN
    The endpoint is not currently live due to an issue identified during user testing.
resources
array

resources is an array of FHIR resources supported by the endpoint

organization
object

The organization is a JSON object that shows the ID and name of the payer associated with the endpoint.

Request

GET
/endpoints
curl https://api.flexpa.com/endpoints \
  -H 'Content-Type: application/json'

Response

[
    {
        "name": "san-francisco-health-plan-test",
        "id": "46062592-1111-4a06-8974-da9589119238",
        "mode": "TEST",
        "label": ["San Francisco Health Plan"],
        "refreshable": false,
        "status": "LIVE",
        "resources": [
            "Account",
            "ActivityDefinition",
            "AdverseEvent",
            "AllergyIntolerance",
            "Appointment",
            ...
        ],
        "organization": {
            "id": "de83b67b-b176-49ef-b83d-8f8edcd45761",
            "name": "San Francisco Health Plan (SFHP)"
        }
    },
    {
        "name": "village-care-max-test",
        "id": "5c34e5d2-bb46-42d3-a1ce-9b9d2d1fec26",
        "mode": "TEST",
        "label": ["VillageCareMAX"],
        "status": "USER_VALIDATED",
        "refreshable": false,
        "refreshValidFor": 86400,
        "maxAuthPeriod": 31536000,
        "resources": [
            "AccessPolicy",
            "Account",
            "ActivityDefinition",
            "AdverseEvent",
            "AidboxConfig",
            ...
        ],
        "organization": {
            "id": "603889da-dc1e-4f67-b0cf-04d76edc2dcf",
            "name": "Horizon Blue Cross Blue Shield of New Jersey"
        }
    }
    ...
]

#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. You must use a server to make requests to the API.

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.

#Next steps

Quickstart

Get started with a cloneable quickstart project

Try it out →

Flexpa Link

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

Build with Flexpa Link →
Status TwitterGitHub

© 2023 Flexpa. All rights reserved.