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

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.

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.

Payers

This API serves as a reference for Flexpa's payer-level network support.

A payer is an entity organizing and administering a health insurance plan. Flexpa federates patient access APIs as FHIR Endpoints across payers.

You can read more about payers and view our payer list here. This API returns the same information found on this page.

Response

name: string; The name of the payer
id: string; The id that Flexpa uses to identify this payer
note: object; The note is used to detail whether the payer supports just CMS plans or all plans (including commercial lives)
type: object; The type details whether the payer record is a payer, a vendor, or another type of entity.

Request

Payers

GET

/payers

curl -X POST https://api.flexpa.com/payers \
  -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"
    },
    ...
]

Endpoints

This API serves as a reference for Flexpa's endpoint-level network support.

Endpoints are:

FHIR REST API servers
Involving an authorization process (SMART)
Created and maintained by health plan payers, health care providers, and tech vendors to support patient access and other regulatory requirements.

You can read more about endpoints and view our endpoint list here. This API returns the same information found on this page.

Response

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: object; The mode is used to detail whether the endpoint is for test or live mode
label: object; 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: object; The refreshable is boolean that indicates whether the endpoint is refreshable and supports off-line access.
payer: object; The payer is a JSON object that shows the ID and name of the payer associated with the endpoint.

Request

Endpoints

GET

/endpoints

curl -X POST 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,
        "resources": [
            "Account",
            "ActivityDefinition",
            "AdverseEvent",
            "AllergyIntolerance",
            "Appointment",
            ...
        ],
        "payer": {
            "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",
        "refreshable": false,
        "resources": [
            "AccessPolicy",
            "Account",
            "ActivityDefinition",
            "AdverseEvent",
            "AidboxConfig",
            ...
        ],
        "payer": {
            "id": "603889da-dc1e-4f67-b0cf-04d76edc2dcf",
            "name": "Horizon Blue Cross Blue Shield of New Jersey"
        }
    }
    ...
 ]

Authentication

The Flexpa API uses API keys and Access Tokens to authenticate requests. You obtain a Patient 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 Patient Access Token.

Access tokens

Exchange

POST https://api.flexpa.com/link/exchange

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.

To exchange a public_token for an access_token send an HTTP POST request to https://api.flexpa.com/link/exchange with a Content-Type: application/json header and a JSON body containing the public_token and your secret_key.

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

Parameters

public_tokenRequired: string; Received from the Flexpa Link onSuccess callback
secret_keyRequired: string; Your Flexpa API secret key

Response

access_token: string; The access_token to be used to make FHIR Requests on behalf of this user
expires_in: string; The expires_in to be used to make FHIR Requests on behalf of this user
endpoint: object; The endpoint to be used to make FHIR Requests on behalf of this user

Request

Exchange

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

Introspect

GET https://api.flexpa.com/link/introspect

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

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

Calling Flexpa API's introspect endpoint
Using a client-side library like jwt-decode

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

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
endpoint: object; The Endpoint to which the patient authorized access to, can be used to determine which health plan the patient connected

Request

Introspect

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

Refresh

POST https://api.flexpa.com/link/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

Response

access_token: string; The access_token to be used to make FHIR requests on behalf of this user

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
OAUTH_ERROR: An error occurred during the refresh exchange
NOT_PERMITTED: Your application does not own this access token

Request

Refresh

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

Questions? Email support

FHIR Resources

GET https://api.flexpa.com/fhir/*

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.

Parameters

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

Response

: The requested FHIR Resource in JSON

Wildcard parameters

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

We highly recommend that you use the $PATIENT_ID wildcard parameter in your API requests to Flexpa in order to simplify your experience.

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.

Example Response

When an endpoint does not support the requested resource you can expect this response:

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

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

Code

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.

Next steps

Flexpa Link

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

Build with Flexpa Link →

Searching Coverage

Retrieve information commonly found on a health insurance card

Read the Coverage guide →