Quickstart
Get started with a cloneable quickstart project
Flexpa Link can be used in an app to authorize access to health plans, claims,
and clinical data. Then, Flexpa API can be used to query electronic medical
records via FHIR resources.
This guide shows you how to build and run Flexpa's quickstart example on GitHub.
Quickstart setup
Let's start by getting the quickstart project running locally on your machine.
This section walks through getting the API keys, cloning the quickstart repo, and running the project.
Get API keys
To use Flexpa, you need valid API keys.
- You can generate Test Mode API keys (recommended for development)
- or contact us for production access.
Once you have the API keys, you're ready to go!
Clone repo
First, clone the quickstart repository. You can do this using HTTPS:
git clone https://github.com/flexpa/quickstart.git
cd quickstart
Set environment variables
You'll need to add your publishable and secret Flexpa API keys to a .env
file in the client and server directories.
Rename the file .env.template
to .env
in both directories.
cp client/.env.template client/.env
cp server/.env.template server/.env
During development, use the Test Mode API keys rather than the production ones.
Open both client/.env
and server/.env
in a text editor and replace the values with your Test Mode API keys.
client/.env
VITE_FLEXPA_PUBLISHABLE_KEY=
server/.env
Run project
First, from the root of the project, run the frontend client:
cd client
nvm use
npm install
npm run dev
Next, from the root of the project in a new terminal, run the backend server:
cd server
nvm use
npm install
npm run build
npm run dev
Open http://localhost:3000 with your browser to see the result.
Check out our test mode guide for a list of payer test logins or log in with Humana using:
How it works
Now that you have the quickstart project running, let's step through some of the main sections.
Flexpa Link configuration
Flexpa Link is included through a script tag inside the head of the HTML
document:
client/index.html
<html>
...
<head>
...
<script src="https://js.flexpa.com/v1/"></script>
...
</head>
...
</html>
Then, in the client-side Javascript code,
FlexpaLink.create()
is called with the publishableKey
and onSuccess
parameters to configure Flexpa Link:
client/src/main.ts
FlexpaLink.create({
publishableKey: import.meta.env.VITE_FLEXPA_PUBLISHABLE_KEY,
onSuccess: async (publicToken: string) => {},
});
Authentication flow
The Flexpa authentication flow helps you obtain authorization to access health plans, coverage, and clinical data directly from a patient.
Read more about which plans Flexpa supports in our Endpoints reference.
To start the authentication flow, FlexpaLink.open()
is called within the onclick
handler of a button.
client/src/main.ts
const linkButton = document.getElementById("flexpa-link-btn");
...
linkButton.addEventListener("click", () => {
FlexpaLink.open();
});
You must call FlexpaLink.create(...)
before calling Flexpa.open()
Once clicked, it presents the user with a modal to link their health plan payer:

Obtain access token
After a user completes the payer login flow, the onSuccess
callback is executed, with a publicToken
as the argument.
client/src/main.ts
FlexpaLink.create({
publishableKey: import.meta.env.VITE_FLEXPA_PUBLISHABLE_KEY,
onSuccess: async (publicToken: string) => {
const resp = await fetch(
`${import.meta.env.VITE_SERVER_URL}/flexpa-access-token`,
{
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ publicToken }),
}
);
},
});
To query patient data, you must exchange the public token for an access token. You can then use the access token to query Flexpa API for patient data.
Visually, the flow looks like:
To exchange the public token for an access token, you must:
- Pass the public token to your server
- Have your server make a
POST
request to https://api.flexpa.com/link/exchange
, passing the public_token
and your secret_key
within the JSON body
- Parse the response JSON body of
https://api.flexpa.com/link/exchange
to extract the access_token
- Pass the access token back to the client
- The client can now query Flexpa API using the wildcard parameter
$PATIENT_ID
to query patient health data!
A minimal endpoint that facilitates the token exchange might look like this:
server/src/routes/flexpa_api_token.ts
router.post("/flexpa-access-token", async (req: Request, res: Response) => {
const { publicToken } = req.body as FlexpaAccessTokenBody;
...
try {
const resp = await fetch(`${process.env.FLEXPA_PUBLIC_API_BASE_URL}/link/exchange`, {
method: "POST",
headers: {
"content-type": "application/json",
},
body: JSON.stringify({
public_token: publicToken,
secret_key: process.env.FLEXPA_API_SECRET_KEY,
}),
});
const { access_token: accessToken, expires_in: expiresIn } = await resp.json() as LinkExchangeResponse;
res.send({ accessToken, expiresIn });
}
catch (err) {
return res.status(500).send(`Error exchanging token: ${err}`);
}
});
Once your client receives the access token, it has everything needed to access patient data using Flexpa API.
Flexpa API FHIR queries
Now that the application has the access token it can make requests to the patient's payer FHIR server through https://api.flexpa.com/fhir
.
Any FHIR resource requests must include:
- access token within the
Authorization
HTTP header
However if you need to reference the currently patientId
for the currently logged in Patient, you can use the wildcard parameter $PATIENT_ID
Flexpa API supports reading and searching a variety of FHIR resources.
See FHIR resources for some examples of the resources we support.
The quickstart example retrieves the Coverage FHIR resource:
client/src/main.ts
const fhirResp = await fetch(
`${
import.meta.env.VITE_FLEXPA_PUBLIC_FHIR_BASE_URL
}/Coverage?patient=$PATIENT_ID`,
{
method: "GET",
headers: {
authorization: `Bearer ${accessToken}`,
},
}
);
Next steps
See the API documentation or follow one of our guides for more information on requesting users' health data.