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 →