API reference

Use the API to retrieve claims and clinical data from a linked health plan

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.

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.

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

URL

The base URL for the Flexpa API is https://api.flexpa.com. All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

Wildcard parameters

Flexpa API supports Wildcard Parameters that can be used in URL query parameters in FHIR Resources API requests.

They 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 - References the patient_id belonging to the access_token.
- Can be used directly in the URL, or with a search parameter of patient (see below).

Examples:

GET /fhir/Patient/$PATIENT_ID
GET /fhir/Coverage?patient=$PATIENT_ID

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

Example

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

Introspect

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

Access tokens are string-encoded JWTs. They can be decoded into an object containing these fields:

iat - when the token was issued
exp - when the token expires
sub - the subject of the JWT (a string in the format of "Patient/<patient_id>")

You can decode the JWT either by:

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

Parameters

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

Response

payload: object; An object containing the iat, exp and sub fields
protectedHeader: object; An object containing the alg field; the algorithm used to sign the JWT

Example

ACCESS_TOKEN=flexpa-link-access-token

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

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

Example:

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

Questions? Reach out to our support teamEmail support

FHIR Resources

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

Currently supports Read and Search requests. Add the FHIR resource you want to Read or Search after the /fhir/ subpath of the URL.

Also supports a wildcard parameter $PATIENT_ID that can be used to reference the patient_id associated with the current access_token

Example: https://api.flexpa.com/fhir/Patient/$PATIENT_ID

You can also pass any parameters as you normally would to a FHIR API:

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

Request fields:

access_token - Passed in as a header.
- Authorization: Bearer ${access_token}.

Response fields: The FHIR resource requested, in JSON format.

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 paging by using the _count parameter in your search request.

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

Payers may also automatically page search results with many records.

If a payer supports paging, they will 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 linked by the patient during authorization returns an OperationOutcome we will response with it directly. If it does not, we will substitute the response with one we create to represent the error.

For example, 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. These are 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

Searching Coverage

Retrieve information commonly found on a health insurance card

Read the Coverage guide →

Flexpa Link

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

Build with Flexpa Link →