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_IDGET /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
Link 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 API key.
- It's important to only call this endpoint from your server, as to not expose your
secret_key.
Request fields:
public_token - received from the Flexpa Link onSuccess callbacksecret_key - your Flexpa API secret key.
Response fields:
access_token - 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>"
}'
Introspecting access tokens
Access tokens are JWTs that contain the encoded fields:
iat - when the token was issuedexp - when the token expiressub - the subject of the JWT (a string in the format of "Patient/<patient_id>")
You can decode the JWT either by:
Introspect endpoint
GET https://api.flexpa.com/link/introspect
Request headers:
Response fields:
payload - an object containing the iat, exp and sub fieldsprotectedHeader - 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: $ACCESS_TOKEN"
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.
Next steps