API Integration
| Time to Complete | 1-2 days |
|---|---|
| Time to Test and Deploy | 1-1.5 weeks |
| Skills Required | Make API calls, build UX |
Complete the 1-Click Health Setup guide before following this API Integration guide.
Please do all development work and testing against our Sandbox environment, which returns mock data. You can use our Production environment when you're ready to go live.
1. Collect inputs.
To start 1-Click Health for a user, you'll need to collect input user data: see 1-Click Health Inputs for details.
Only First Name, Last Name, and Birth Date are required, but the more inputs you provide, the higher coverage and accuracy will be. Because 1-Click Health is billed per attempt (not just per success), it's well worth collecting more inputs upfront.
We strongly recommend using 1-Click Signup to collect these inputs. With 1-Click Signup, you can collect all of these inputs in less than 10 seconds, from as little as a user's phone number!
You'll also need to:
If you use 1-Click Signup to collect the inputs, you can put the consent language and graphic on the first screen (typically the Phone screen): see the first example below. If you instead ask the user to manually enter the inputs, you can put them on that screen: see the second and third examples below. We recommend that you use a single screen with fields for each input you want to collect: see the Info screen of our User Experience guide for full details. Here are examples:
Verified consent language (the health insurance variant) on the first screen of 1-Click Signup
1-Click Signup can autofill all inputs for 1-Click Health!
Verified consent language (the health insurance variant) on a manual entry screen, with minimal inputs
Verified consent language (the health insurance variant) on a manual entry screen, with maximal inputs
a. Include the Verified consent language.
Regulations require that users give informed consent, so you must use our consent language before you start the 1-Click Health flow. It can be included alongside or as part of other legal language you already use, but it must be displayed to the user — not just included in terms you link out to.
Use this language:
By
{taking this action}, I agree that Verified ({Brand Name}’s service provider) and its vendors may receive my personal info and provide{Brand Name}with more info about me, including my health insurance.
- Replace
{taking this action}with the action the user will take to start 1-Click Health. For example:- If you start with 1-Click Signup, using a form with a phone number input that autosubmits (which we recommend), you should use "entering my phone number".
- If you use a Continue button, you should use "clicking 'Continue'".
- Link "Verified" to https://verified.inc and make it underlined and a different color than the rest of the text (so the user knows it's a link).
- Replace
{Brand Name}with your brand name.
Here's an example:
By entering my phone number, I agree that Verified (Hooli’s service provider) and its vendors may receive my personal info and provide to Hooli more info about me, including my health insurance.
If you use 1-Click Signup to autofill SSNs as an input for 1-Click Health, you need to have "including my social security number" in the consent language, as described here in the 1-Click Signup API Integration guide. In this case, the consent language should be:
By
{taking this action}, I agree that Verified ({Brand Name}’s service provider) and its vendors may receive my personal info and provide{Brand Name}with more info about me, including my social security number and health insurance.
So, for example:
By entering my phone number, I agree that Verified (Hooli’s service provider) and its vendors may receive my personal info and provide to Hooli more info about me, including my social security number and health insurance.
b. Include a "Powered by Verified" graphic.
We require you to include a "Powered by Verified" graphic, which helps ensure the user gives legally valid consent for us to source data for them.
The graphic should be placed alongside the consent language.
We provide many different variants of the graphic, so you can choose the one that best fits your use case and the background color of your application:
"Powered By Verified" Graphic Variants
Powered by Verified
Black and Green:
White and Green:
Black:
White:
Gray:
1-Click Signup powered by Verified
Black and Green:
White and Green:
Black:
White:
Gray:
1-Click Health powered by Verified
Black and Green:
White and Green:
Black:
White:
Gray:
1-Click Login powered by Verified
Black and Green:
White and Green:
Black:
White:
Gray:
1-Click Verify powered by Verified
Black and Green:
White and Green:
Black:
White:
Gray:
1-Click Apply powered by Verified
Black and Green:
White and Green:
Black:
White:
Gray:
1-Click Access powered by Verified
Black and Green:
White and Green:
Black:
White:
Gray:
1-Click AutoFill powered by Verified
Black and Green:
White and Green:
Black:
White:
Gray:
2. Call POST /1-click/health.
Call POST /1-click/health with the inputs you collected:
{
fullName: {
firstName: string, // required
middleName?: string,
lastName: string // required
},
birthDate: string, // required
address?: {
line1?: string,
line2?: string,
city?: string,
state?: string,
zipCode?: string,
country?: string
},
sex?: string,
ssn?: string,
npi?: string
}
Never use Verified API keys client side. Only use them server side. Verified API keys allow you to source sensitive data about users, so you must keep them secure. If you use a Verified API key client side, our firewall will block your request, and you'll get this firewall error.
1-Click Signup is synchronous (with almost all response times under 1 second), so you receive data directly in the response body of POST /1-click.
But 1-Click Health is asynchronous, because it takes longer to search for a user's health insurance plans across the large number of possible payers. Response times are typically 10-25 seconds, so you don't receive data in the response body of POST /1-click/health but rather via webhook or by polling GET /1-click/health. See step 3 for details.
The response body will contain a healthDataUuid that identifies the 1-Click Health flow:
{
healthDataUuid: string,
status: "PENDING" | "PROCESSING" | "SUCCEEDED" | "FAILED" | "PARTIAL"
}
See POST /1-click/health for details.
3. Receive outputs.
If you configured the webhook setting in the Verified Dashboard, we'll send the 1-Click Health response as a payload to your webhook.
See the Webhooks page for general details about how Verified handles webhooks.
You can alternatively poll the GET /1-click/health endpoint until you receive a response. To do so, repeatedly call GET /1-click/health/{healthDataUuid}, using the value of healthDataUuid from the response body of POST /1-click/health.
You can retrieve data for 30 minutes, at which point it's deleted. If you need to retrieve the same data again, use GET /1-click/health instead of POST /1-click/health so that a duplicate 1-Click Health event isn't created (and so you aren't billed twice).
The response will contain a 1ClickHealthEntity (see this example). There are two cases:
- Success: If we can source health insurance data for the user, the
1ClickHealthEntitywill containresultswith one or more health insurance plans.
→ Continue to step 4. - Failure: Otherwise, the
1ClickHealthEntitywill containerrorsindicating that the lookup failed.
→ Fall back to a manual health insurance entry flow.
4. Prompt user to confirm.
For each health insurance plan you might use for a user, you must display the Payer Name and Member ID for the user to confirm. These are contained in memberId and payer.name, respectively, for a given plan within the results array of the 1ClickHealthEntity.
You don't need to display the full X12 EDI 271 (Health Care Eligibility Benefit Response, contained in edi_271) — and you shouldn't, because it's not human readable!
You may not store a user's health insurance data if they don't confirm it. This is a compliance requirement. We will not approve your integration if you don't abide by it.
- Transparency: By displaying the user's data to them, you ensure they're aware of what data you've received about them.
- Accuracy: Although Verified provides very high quality data, we can never guarantee all data will be perfectly accurate. By having the user confirm their data, you can better avoid inaccuracies. Depending on your use case, you may want to give the user the ability to edit their data.
We require you to mask Member IDs because they're particularly sensitive:
- Mask at least 3 middle characters server side, so the client only displays the starting and ending characters. This preserves privacy while making it easy for the user to confirm the value. Note that Member IDs are alphanumeric and variable in length, so masking must be done thoughtfully. Email us at Support@Verified.inc if you need guidance.
- If you allow the user to edit the Member ID, clear the entire value when they start editing, so they don't just edit visible characters (which could result in another valid Member ID, but one that isn't theirs).
We recommend that you:
- Use a static display for view mode.
- Use a form with autofilled inputs for edit mode.
- Include information about where the data comes from.
(See the Info screen of our User Experience guide for full details.) Here's an example:
Static display for view mode, question mark button to see information about where data comes from
Form with autofilled inputs for edit mode, question mark button to see information about where data comes from
Information about where data comes from
a. Use a static display for view mode.
In edit mode, we recommend that you display the user's data statically and show an edit button that lets them go into edit mode.
If you receive multiple health insurance plans (in the results array of the 1ClickHealthEntity), you can display a dropdown of options. If the user goes into edit mode, you should use the selected value in the dropdown to autofill inputs.
b. Use a form with autofilled inputs for edit mode.
In edit mode, we recommend that you display the user's data using a form with autofilled inputs.
You can enable or disable each input depending on whether you want the user to be able to edit the data it contains. The upside of allowing the user to edit data is that it allows them to correct any inaccuracies. The downside is that user input isn't verified and may make fraud more likely.
c. Include information about where the data comes from.
Including some information about where the data comes from helps users understand the magic of 1-Click Health and feel comfortable with it. We recommend this language:
Verified autofills your info from trusted sources so you don’t have to enter it manually. It’s fast, safe, and secure.
We cannot guarantee that autofilled health insurance data is accurate, especially if you sourced it using inputs not autofilled by 1-Click Signup. It's possible that the insurance a user submits is inaccurate.
So, you must verify a user's identity in some other way before using their insurance. This is an important step to prevent insurance inaccuracy or fraud – and to make sure you're paid by insurance!
Go Live!
Request Approval
When you're ready to go live, request approval for Production access:
- Go to the Brand Details page for your brand in the Verified Dashboard.
- Click the Production tab in the upper right, and make sure your brand settings are configured as you intend them to be.
- Click the Request Approval button under the API Keys section.
- Complete the steps listed in the dialog.
- Click the Submit Request button.
You can use the Sync from Sandbox buttons to quickly port some setting configurations from Sandbox to Production. Note, however, that this is not possible for all settings: some need to be configured manually for Production.
In step 4, you'll be asked to confirm the following:
You'll also be prompted to share a link to your Sandbox integration and/or schedule a 15 minute call with us, so we can review your integration to see that it's compliant and working properly. Once we approve it, you'll have access to a Production API key on the Brand Details page.
Swap Sandbox for Production
Once you have Production access, just swap Sandbox for Production:
- Swap your Sandbox API key for your Production API key.
- Swap the Sandbox base URL for the Production base URL.
Then you'll be live with 1-Click Signup! ✅