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.

Make sure you have NodeJS (v16.14.2+) and npm installed on your machine before beginning the setup.

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:

# 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.

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
FLEXPA_API_SECRET_KEY=

Run 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

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

Check out our test mode guide for a list of test credentials.

Questions? Reach out to our support teamEmail support

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, // Defined in .env
  onSuccess: async (publicToken: string) => {}, // We'll talk about the onSuccess callback later
});

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 FlexpaLink.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) => {
    /*  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:

Diagram of public token to access token exchange flow

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
/**
* POST /flexpa-access-token
* Exchanges your `publicToken` for an `access_token`
*/
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`
  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 // https://api.flexpa.com/fhir
  }/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.

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 →