Flexpa Link
Adding Flexpa Link to your app lets your users authorize access to their health plan data. Your app can then use the Flexpa API to retrieve patient health plan and clinical data.
Flexpa Link handles the SMART on FHIR authentication flow and error handling for each health data source that we support. Flexpa Link works across all modern browsers.
To use Flexpa Link you need:
- A frontend app to start the authentication flow with a user. Flexpa Link runs in an
<iframe> and can be added to your frontend with a <script> tag.
- A backend web server to complete the authentication flow (see below).
- A pair of API Keys. Register in the Flexpa Portal today or contact us about enterprise plans.
Authentication flow
The diagram below shows how Flexpa Link is used to obtain a public_token, which is exchanged for a patient access_token, which is finally used with the Flexpa API.
The flow starts when your user wants to connect their plan data to your app.
Your frontend application opens Flexpa Link with your publishable_key using the create() and open() functions in the install step below.
In the onSuccess callback you will receive a public_token.
You must exchange the public_token (along with your secret_key) for a functioning access_token.
This step happens on your backend server.
Use the access_token to make requests to Flexpa API to access the user's health plan data.
Install
You can add Flexpa Link to your application within a couple of minutes.
Inside an HTML document add the Flexpa Link script to create a global FlexpaLink object in your application:
Add script tag
<head>
...
<script src="https://js.flexpa.com/v1/"></script>
</head>
Create
Next, initialize FlexpaLink by calling create(). Use your publishable_key_test or publishable_key_live key from the Flexpa Portal:
Initialize FlexpaLink
FlexpaLink.create({
// Replace with your publishable key
publishableKey: '...',
onSuccess: (publicToken) => {
// Send `publicToken` to your backend to exchange it for a patient `access_token`
// https://www.flexpa.com/docs/sdk/login#exchange
console.log('publicToken: ', publicToken);
},
});
Parameters
- publishableKeyRequired
- string
The unique key to identify your app provided to you during registration at portal.flexpa.com.
- onSuccessRequired
- (publicToken: string) => void
This callback is executed when a patient successfully authorizes access to their health plan. The only
parameter is a publicToken which is used in the Exchange
step to complete the authorization flow.
- onLoad
- () => void
This callback is executed when Flexpa Link has finished loading after calling open.
- onExit
- () => void
This callback is executed whenever a patient exits the Flexpa Link flow without successfully authorizing access to their health plan.
- endpoint
- string
An optional UUID string for an Endpoint.
Providing this value skips the search-and-select health plan step in the authorization flow.
Open
To start the authentication flow where your users connect their health data, use the open() function on the FlexpaLink object. For example, opening on a button click:
<button onclick="FlexpaLink.open()">Connect your health data</button>
Parameters
- endpoint
- string
An optional UUID string for an Endpoint
. Providing this value skips the search-and-select health plan step in the authorization flow. This value
also overrides the same-named value provided to the Create step.
Exchange public token for access token
When a user successfully links a health data source, FlexpaLink calls the onSuccess callback defined in the Create step. This callback receives a public_token. For security reasons, this public_token cannot be used to access the Flexpa API directly. Instead, it must be exchanged for an access_token.
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.
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": "sk_test..."
}'
That's it! You now have an access_token to make requests to Flexpa API.
During the process of exchanging a public token for an access token, Flexpa Link stores the patient ID received in the response from the server in a wildcard, $PATIENT_ID, which you can and should use in subsequent API requests.
Embedding Flexpa Link
Here are different techniques for embedding Flexpa Link into your application or service to ensure participation of new users and activate existing users:
Onboarding process integration
Incorporate Flexpa Link directly into your new user onboarding experience. New users have higher engagement as completion of enrollment is a compelling event to complete the Flexpa Link flow.
As these users sign up and learn to navigate your application, prompt them to link their payer account through Flexpa. This could be presented as an initial setup step, or as a highlighted feature in a tutorial. Make sure to explain the benefits and reassure the user about the security of the process.
Integration in existing patient applications
Embed Flexpa Link as an activity or option within your existing patient interface. This could be as a button, a banner, or a new tab in a user's profile settings. Explain the value of linking their payer account and gently prompt users to do so.
Personalized user dashboard
On the user's profile or dashboard, you can include a personalized status or progress bar indicating the completion of their profile setup, including whether they've linked their payer account. This visual cue can motivate users to complete their setup for existing users, including linking their payer account via Flexpa Link.
Customized user experience
Customize the user's experience based on whether they have linked their payer account or not. For those who have not linked their account, display a banner or a dedicated space on their dashboard, encouraging them to link their payer account. For those who have linked their accounts, this space could be replaced with more advanced features or personalized content.
In-app notifications
In-app notifications can be a powerful tool for existing users. Use pop-up messages or notifications in your application to remind users to link their payer accounts via Flexpa Link. These can be triggered based on certain user behaviors, for example, when a user logs in, when they navigate to certain sections of the app, or when they have been inactive for a while.
Make sure these reminders are not too intrusive and are designed in a way that clearly communicates the value of the action.
Additional techniques
Regardless of whether a user is new or existing, sometimes they need a little extra direction to complete the Flexpa Link flow. Here are some additional techniques to encourage users to link their payer account:
Campaigns
In-app notifications may not be suited for all applications' populations. Send targeted marketing campaigns to encourage users to link their payer accounts through Flexpa. This can be done via:
- Email: Craft an informative email explaining the benefits of linking a payer account and how to do it. Include a direct link to the Flexpa Link in your application.
- SMS: Send a short, compelling message with a direct link to your application where users can easily link their payer accounts. Ensure the message is concise yet informative.
- Paper Mail: For users who might not be as tech-savvy, consider sending a physical mailer that explains the benefits of Flexpa and how to link their payer account. Include clear, step-by-step instructions.
- Social Media and Blog Posts: Use your online platforms to educate users about the benefits of linking their payer account using Flexpa Link. Highlight user testimonials, case studies, or create educational content about the importance and benefits of linking payer accounts.
Incentivization
Consider offering small incentives or rewards for users who link their payer account. This could be in the form of discounts, access to premium features, or other value-added benefits. Incentives can be a powerful motivator for users to take action.
Best practices
Below are some principles we typically recommend to optimize user conversion via Flexpa Link and ensure your users complete the authentication flow. Some recommendations may be less applicable to your workflow.
Explain the benefit to the user
Your UI should tell the user why they want to use Flexpa and the value they get from linking their payer. For example, linking their payer account might save them time inputting medication data manually. Or it can enable your app to present more relevant, tailored Medicare plan recommendations.
Tell the user what to expect
Before launching the Flexpa flow, explain to the user that they'll be prompted to link a payer account. Explain that they'll need to input their username and password, but also that they can create an account with their payer if they do not have one. Explain what data your app collects from their account, and why it's needed.
Present Flexpa as the default
Rather than presenting Flexpa and manual flows as equal alternatives, encourage your customers to use Flexpa through the size, positioning, and color of the Flexpa Link entry point. You can also use labels such as "Recommended" or "Preferred".
Explain that Flexpa is secure
Let customers know that Flexpa Link is secure and uses 256-bit encryption; a lock icon can also be used to help convey that Flexpa uses encryption. Explain how patients can control their data and remove connectivity through Flexpa Connections.
Provide a polished, engaging flow
A Flexpa hosting flow that is aesthetically engaging, polished, and reflects your brand conveys the legitimacy and importance of linking an account. Illustrations and interactive elements can all be a part of your pre-Flexpa messaging.
Allow for linking multiple plans
Patients sometimes have multiple payer accounts, such as a primary and secondary insurance for dual eligibles or a current and prior insurance for members who have changed carriers. To capture all of this information, allow patients to link multiple accounts to your app, and make it clear that they can do so.
Next steps