Quickstart

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.

See this in action by building and running Flexpa's quickstart application hosted on GitHub. After that, continue reading to learn how the application works so you can modify this example for your own uses.

Quickstart setup

Let's start by getting the quickstart project running locally on your machine. This section walks through cloning the quickstart repo, setting your API keys, running the project, and testing it.

The quickstart assumes you have NodeJS (v16.14.2+) and npm already installed.

Clone repo

First, clone the quickstart repository:

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

Set API keys

Second, create an account in the Flexpa Portal to get your test mode keys. You can contact us later for live mode access.

You'll need to add your publishable and secret API keys to the .env files in the client and server directories.

Rename the .env.template file as .env in both directories.

cd quickstart
cp client/.env.template client/.env 
cp server/.env.template server/.env

Open both client/.env and server/.env and add your test mode API keys.

client/.env
VITE_FLEXPA_PUBLISHABLE_KEY=

server/.env
FLEXPA_API_SECRET_KEY=

Run project

The quickstart code includes two components:

Frontend client for creating the Flexpa Link connection to a health plan
Backend server that swaps a public token for an access token

Run both components simultaneously to test the application.

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 the 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 the dependencies
npm install

# Compile the TypeScript to JavaScript code
npm run build

# Run the backend server
npm run dev

Test application

To test the quickstart app:

Open http://localhost:3000 in your browser.
Click the "Connect your health plan with Flexpa Link" to open the Flexpa Link modal.
Select any health plan payer from the list.
When directed to the provider's site, authenticate using a test mode login.
When Flexpa Link indicates success, click "Continue".

Upon successful authentication, you'll be redirected back to localhost. The server script automatically exchanges the public token for an access token, and then the client app performs a FHIR request and reports upon the result. (This may take a moment to complete.)

Questions? Email support

How it works

Now that you've seen the application in action, let's examine 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, the button presents the user with a modal to connect 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. To query patient data, you must exchange the public token for an access token using your secret API key (i.e., from the server). Here's an updated Flexpa Link configuration with that callback definition:

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 
        defined 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 }),
      }
    );
  },
});

After the server swaps the public token for an access token you can use the access token to query Flexpa API for patient data. 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!

Here is a minimal endpoint that performs the token exchange:

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

Once the application has the access token it can make requests to the patient's payer FHIR server through https://api.flexpa.com/fhir. All FHIR Resource requests must include the access token within the Authorization HTTP header.

For FHIR endpoints that need a patient ID, Flexpa API automatically pulls the patient ID from the access token when you use the wildcard parameter $PATIENT_ID.

Flexpa API supports reading and searching a variety of FHIR Resources. 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

Searching Coverage

Retrieve information commonly found on a health insurance card

Read the Coverage guide →

Explanation of Benefits

Retrieve Explanation of Benefits statements with detailed claims histories

Read the EOB Guide →