Quickstart

Get started with a cloneable quickstart project

Goal

Flexpa Link can be used in an app to authorize access to health plan, 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 will walk through getting the API keys, cloning the quickstart repo, and running the project.

Get API Keys

To use Flexpa, you will 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!

Make sure you have NodeJS and npm installed on your machine before beginning the setup. You will also need a terminal capable of running basic Unix commands.

Clone Repo

First, clone the quickstart repository. You can do this using HTTPS:

# Clone the quickstart project repository

git clone https://github.com/flexpa/quickstart.git

# Navigate into the root of the project

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 and update the values to your publishable and secret keys.

cp client/.env.template client/.env
cp server/.env.template server/.env

During development, you will need to 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. Remember to save!

client/.env
VITE_FLEXPA_PUBLISHABLE_KEY=

server/.env
FLEXPA_API_SECRET_KEY=

Run the Project

First, from the root of the project, run the frontend client:

# Navigate into the client directory
cd client

# Set the correct node version
nvm use

# Install dependencies
npm install

# Run the frontend server
npm run dev

Next, from the root of the project in a new terminal, run the backend server:

# Navigate into the server directory
cd server

# Set the correct node version
nvm use

# Install dependencies
npm install

# Compile the Typescript to Javascript code
npm run build

# Run the backend server
npm run dev

Note: nvm is not supported on Windows. If you are using Windows, ensure you have the correct version of Node installed. See .nvmrc for the recommended version.

Open http://localhost:3000 with your browser to see the result.

You can use the following test patient login with Humana:

Username:

Password:
HUser00007

PW00007!

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 parameters to configure Flexpa Link:

client/src/main.ts
FlexpaLink.create({
  publishableKey: import.meta.env.VITE_FLEXPA_PUBLISHABLE_KEY, // Defined in .env
  onSuccess: async (publicToken: string) => {}, // We'll talk about the onSuccess callback later
});

Triggering the Authentication Flow

The Flexpa authentication flow helps you obtain authorization to access health plan, 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:

Obtaining an Access Token

After a user completes the payer login flow, the onSuccess callback is executed, with a public_token as the argument.

client/src/main.ts
FlexpaLink.create({
  publishableKey: import.meta.env.VITE_FLEXPA_PUBLISHABLE_KEY,
  onSuccess: async (publicToken: string) => {
    /*  Make a request to the `POST /flexpa-access-token` endpoint that we wrote in `server`.
        Include the `publicToken` in the body. */
    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 and patient id
Pass the access token and patient id back to the client
The client now has everything it needs to query patient health data!

A minimal endpoint that facilitates the token exchange might look like this:

server/src/routes/flexpa_api_token.ts
/**
* POST /flexpa-access-token
* Exchanges your `publicToken` for an `access_token` and `patient_id`
*/
router.post("/flexpa-access-token", async (req: Request, res: Response) => {
  const { publicToken } = req.body as FlexpaAccessTokenBody;
  ...
  // Call Flexpa API's exchange endpoint to exchange your `publicToken` for an `access_token` and a `patient_id`
  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, patient_id: patientId, expires_in: expiresIn } = await resp.json() as LinkExchangeResponse;

    res.send({ accessToken, patientId, expiresIn });
  }
  catch (err) {
    return res.status(500).send(`Error exchanging token: ${err}`);
  }

});

Once your client receives the access token and patient id, it has everything needed to access patient data using Flexpa API.

Flexpa API FHIR Queries

Now that the application has the access token and patient id, it can make requests to the patient's payer FHIR server through https://api.flexpa.com/fhir.

Any FHIR resource requests must include:

patientId in the query parameter and
accessToken within the authorization HTTP header

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 // https://api.flexpa.com/fhir
  }/Coverage?patient=${patientId}`,
  {
    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.

API Reference

Use Flexpa API as a unified API to access Explanation of Benefits and more

Build with Flexpa API →

Explanation of Benefits

Retrieve Explanation of Benefits statements with detailed claims histories

Read the EOB Guide →