Flexpa
Contact usDeveloper Portal

Getting started

  • Introduction
  • Quickstart
  • Use cases
  • Pricing
  • Patient access
  • Test mode
  • Going live
  • What we don't do
  • ChangelogUpdated
  • FAQ

Guides

  • Reading resources
  • Searching resources

Network

  • Payers
  • Endpoints

Tools

  • Flexpa Link
  • Flexpa API
  • Data analytics
  • Connections

FHIR Resources

  • Overview
  • AllergyIntolerance
  • CapabilityStatement
  • CarePlan
  • CareTeam
  • Condition
  • Coverage
  • Device
  • DiagnosticReport
  • DocumentReference
  • Encounter
  • ExplanationOfBenefit
  • Goal
  • Immunization
  • Location
  • Medication
  • MedicationDispense
  • MedicationRequest
  • Observation
  • Organization
  • Patient
  • Practitioner
  • PractitionerRole
  • Procedure
  • Provenance

About

  • Handbook
  • Brand kit
  • Join us
  • Privacy Policy
  • Privacy Notice
  • Security
  • Terms of Service

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

© 2023 Flexpa. All rights reserved.

On this page
  • URL
  • Open APIs
  • Payers
  • Endpoints
  • Authentication
  • Access tokens
  • Exchange
  • Introspect
  • Refresh
  • FHIR Resources
  • Wildcard parameters
  • Pagination
  • Errors
  • Next steps