API Reference
Use the API to retrieve claims and clinical data from a linked health plan
Introduction
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.
Modes
Flexpa has two environments, or operating modes.
Get started immediately with test patient credentials. API calls return simulated data in test mode. Use this mode as you build your app.
Launch your app with live patient credentials. API calls return real data in Live mode.
Keys
Each app uses one pair of API keys for each environment for a total of four. Each pair consists of a public and secret part.
A unique key to identify your app, may be used on the client-side.
A confidential secret that you must not share publicly.
Test Mode Keys
Generate your own set of Test Mode API keys to get started
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.
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
callback
secret_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
patient_id
- the FHIR Identifier that uniquely corresponds to this Patient.
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 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:
Introspect Endpoint
GET https://api.flexpa.com/smart/introspect
Request headers:
Response fields:
payload
- an object containing the iat
, exp
and sub
fields
protectedHeader
- 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/smart/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.
Example: https://api.flexpa.com/fhir/Patient/123
You can also pass any paramters as you normally would to a FHIR API:
Example: https://api.flexpa.com/fhir/Coverage?patient=Patient/123
Request fields:
access_token
- Passed in as a header.
Authorization: Bearer ${access_token}
.
Response fields:
The FHIR resource requested, in JSON format.
Coverage
GET https://api.flexpa.com/fhir/Coverage
Sample curl
FLEXPA_API=https://api.flexpa.com/fhir
ACCESS_TOKEN=flexpa-link-access-token
PATIENT_ID=Patient/A000123
curl "$FLEXPA_API/Coverage?patient=$PATIENT_ID" \
-H "Authorization: Bearer $ACCESS_TOKEN"
ExplanationOfBenefit
GET https://api.flexpa.com/fhir/ExplanationOfBenefit
Sample curl
FLEXPA_API=https://api.flexpa.com/fhir
ACCESS_TOKEN=flexpa-link-access-token
PATIENT_ID=Patient/A000123
curl "$FLEXPA_API/ExplanationOfBenefit?patient=$PATIENT_ID" \
-H "Authorization: Bearer $ACCESS_TOKEN"
MedicationRequest
GET https://api.flexpa.com/fhir/MedicationRequest
Sample curl
FLEXPA_API=https://api.flexpa.com/fhir
ACCESS_TOKEN=flexpa-link-access-token
PATIENT_ID=Patient/A000123
curl "$FLEXPA_API/MedicationRequest?patient=$PATIENT_ID" \
-H "Authorization: Bearer $ACCESS_TOKEN"
Procedure
GET https://api.flexpa.com/fhir/Procedure
Sample curl
FLEXPA_API=https://api.flexpa.com/fhir
ACCESS_TOKEN=flexpa-link-access-token
PATIENT_ID=Patient/A000123
curl "$FLEXPA_API/Procedure?patient=$PATIENT_ID" \
-H "Authorization: Bearer $ACCESS_TOKEN"
Observation
GET https://api.flexpa.com/fhir/Observation
Sample curl
FLEXPA_API=https://api.flexpa.com/fhir
ACCESS_TOKEN=flexpa-link-access-token
PATIENT_ID=Patient/A000123
curl "$FLEXPA_API/Observation?patient=$PATIENT_ID" \
-H "Authorization: Bearer $ACCESS_TOKEN"
We can also request Observations(and any other resources) that conform to a specific profile
Sample curl
FLEXPA_API=https://api.flexpa.com/fhir
ACCESS_TOKEN=flexpa-link-access-token
PATIENT_ID=Patient/A000123
PROFILE=http://hl7.org/fhir/us/core/StructureDefinition/us-core-vital-signs
curl "$FLEXPA_API/Observation?patient=$PATIENT_ID&_profile=$PROFILE" \
-H "Authorization: Bearer $ACCESS_TOKEN"
Encounter
GET https://api.flexpa.com/fhir/Encounter
Sample curl
FLEXPA_API=https://api.flexpa.com/fhir
ACCESS_TOKEN=flexpa-link-access-token
PATIENT_ID=Patient/A000123
curl "$FLEXPA_API/Encounter?patient=$PATIENT_ID" \
-H "Authorization: Bearer $ACCESS_TOKEN"
Condition
GET https://api.flexpa.com/fhir/Condition
Sample curl
FLEXPA_API=https://api.flexpa.com/fhir
ACCESS_TOKEN=flexpa-link-access-token
PATIENT_ID=Patient/A000123
curl "$FLEXPA_API/Condition?patient=$PATIENT_ID" \
-H "Authorization: Bearer $ACCESS_TOKEN"
CareTeam
GET https://api.flexpa.com/fhir/CareTeam
Sample curl
FLEXPA_API=https://api.flexpa.com/fhir
ACCESS_TOKEN=flexpa-link-access-token
PATIENT_ID=Patient/A000123
curl "$FLEXPA_API/CareTeam?patient=$PATIENT_ID" \
-H "Authorization: Bearer $ACCESS_TOKEN"