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