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 and includes support for both English and Spanish.
Let us know if there are other langugages you'd like supported.
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
- publishableKeystringRequired
The unique key to identify your app provided to you during registration at portal.flexpa.com.
- onSuccess(publicToken: string) => voidRequired
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(error?: { code: string }) => void
This callback is executed whenever a patient exits the Flexpa Link flow without successfully authorizing access to their health plan. This could occur because the patient abandoned the flow or because of an error. If there was an error, the first argument will be an object with the interface { code: string }.
The code will be one of these values if the payer returned an error in the query string of the callback request to Flexpa:
AUTHORIZATION_CODE_EXCHANGE
The payer's endpoint returned an error after authorization when exchanging an authorization code for an access token.
The callback from payer's endpoint was not properly formatted.
The payer's endpoint returned an invalid state parameter.
Flexpa was unable to synchronize the data successfully to the cache after authorization.
The payer's endpoint did not grant access to the patient. This may occur if the patient clicks "do not consent" on some payer consent screens but can also occur for other reasons.
The payer's endpoint timed out before it could fulfill the request.
The payer has not made the selected plan accessible via their API. This may occur if the payer does not support API access for certain plan types.
The payer's endpoint did not understand the request.
The payer's endpoint experienced an internal server error.
The payer's endpoint configuration needs to be updated by a Flexpa admin.
The payer's scope configuration needs to be updated by a Flexpa admin.
If code contains a value which is not listed above, please submit a bug report to support@flexpa.com.
- endpointstring
An optional UUID string for an Endpoint.
Providing this value skips the search-and-select health plan step in the authorization flow.
- autoExitboolean
An optional boolean to control the exit behavior on successful authorizations.
When false, the sucess screen will not automatically close and will require the patient to click continue. Defaults to true.
- userobject
An optional object specifying information about the end user who will be linking their account.
Providing this object yields the following outcomes:
- 1. The user can be associated with multiple Patient Access Tokens, allowing for improved insights into user behavior.
- 2. Flexpa enforces logical isolation of the user's data between family members if the payer does not implement appropriate Access Control Limits.
- externalIdstringRequired
A unique identifier of the user as that is owned by the host application.
#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
- endpointstring
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.
The public_token is valid for 30 minutes and can only be used once.
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.
You will also receive an expires_in value (e.g. 3600).
This represents the time in seconds for which the access_token is valid, after which your application will be required to make an API request to https://api.flexpa.com/link/refresh.
If available, you will additionally receive a refresh_expires_in value (e.g. 86400).
This represents the time in seconds for which the access_token is refreshable, after which the user will be required to re-authorize your application to the payer.
The availability of refresh_expires_in is subject to the payer's support of the feature.
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.
You should use the wildcard in subsequent API requests.
#Mobile applications
Flexpa Link is normally installed in a browser application. It is possible to install Flexpa Link in a mobile application. For mobile applications, we recommend installing Flexpa Link inside an in-app browser.
#iOS
SFSafariViewController is a way to launch mobile Safari inside of your application (similarly to, but different from, a web view).
Using SFSafariViewController is the recommended approach to implementing Flexpa Link in iOS.
This is because using SFSafariViewController has the following notable benefits:
- Works out of the box, with a relatively small development effort required.
- Behaves like a fully featured Safari browser, including a built-in navigation bar, toolbar, reader mode, and the ability to use Safari's cookies and settings.
- Supports AutoFill, which may help users log in to their payer, improving login success rates.
- Includes accessibility features, such as resizable fonts.
- Provides security features. For example, the current page's domain is always visible to the user.
However, please note that using SFSafariViewController has the following drawbacks:
- Users are required to tap 'Done' at the end of the Flexpa Link authentication flow to close the in-app browser.
- Generally speaking
SFSafariViewController is not very customizable. For example, your application cannot inject JavaScript, handle navigation events, or modify the DOM.
The following example code was generated for iOS 16.4.
FlexpaLink in iOS
//
// SafariViewOption.swift
// LinkExample
//
// Created by Flexpa
//
import SwiftUI
import SafariServices
// This approach uses SFSafariViewController and works out of box.
// 1. SafariView wrapper for SFSafariViewController
struct SafariView: UIViewControllerRepresentable {
let url: URL
func makeUIViewController(context: Context) -> SFSafariViewController {
return SFSafariViewController(url: url)
}
func updateUIViewController(_ uiViewController: SFSafariViewController, context: Context) {
// Can be left empty for this use case
}
}
// 2. Example View
struct SafariViewOption: View {
@State private var showSafari: Bool = false
// Here, replace this URL with the web page that you are loading Flexpa Link on.
// We've used the my.flexpa.com demo app here to show it working end to end.
let url: URL? = URL(string: "https://my.flexpa.com")
var body: some View {
VStack {
Text("Open Flexpa Link").onTapGesture {
showSafari.toggle()
}
}
.padding()
.sheet(isPresented: $showSafari, content: {
if let validURL = url {
SafariView(url: validURL)
}
})
}
}
struct SafariViewOption_Previews: PreviewProvider {
static var previews: some View {
SafariViewOption()
}
}
#Embedding
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, you could notify 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 might 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