Skip to main content

API Integration

Time to Complete2-4 days
Time to Test and Deploy1-2 weeks
Skills RequiredMake API calls, send SMS, build UX
tip

Complete the Setup guide before following this API Integration guide.


Use Sandbox for Development and Testing

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. Prompt user for phone number and verify it.​

To start 1-Click Signup for a user (using the Non-Hosted integration type), you'll need their phone number, and you'll need to verify it using your own solution. You can do this however you like, as long as you verify the user's phone number with a one-time verification code at least 6 digits long.

Supported Phone Numbers

Currently, we only support US mobile phone numbers. You'll need to pass these to our API in E.164 format. This is the +1 country code with a 10-digit subscriber code appended to it, for example +12125550010.

We're able to source verified data for about 95% of these phone numbers. If we can't source data, you can take the user through your normal signup flow.

See our Demo for an example of this.

You'll also need to:

  1. Include the Verified consent language.
  2. Include a "powered by Verified" graphic.

We recommend using a phone number input that auto submits when the user enters 10 digits. (See the Phone screen of our User Experience guide for full details.) Here's an example:

Verified consent language, phone number input, and the green signup variant of the "powered by" graphic

Regulations require that users give informed consent, so you must our consent language where you start the 1-Click Signup flow. It can be included alongside or as part of other legal language you already use, but it must be displayed to the user and 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 autofill more info about me, including my social security number.

  • Replace {taking this action} with the action the user will take to start 1-Click Signup. For example:
    • If you use 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 autofill more info about me, including my social security number.

b. Include a "powered by Verified" graphic.​

We require you to include a graphic that says "1-Click Signup powered by Verified". This helps the user understand they're about to go through a 1-Click flow — and motivates them to do so, since a 1-click experience is always best!

The graphic should be placed just below the trigger you use to start the 1-Click Signup flow. Usually, this is a phone number or birthday input or a button.

We provide several variants of the graphic, with different words than "Signup" and in different colors, in both SVG and PNG format. Choose the one you prefer and that best fits the background color of your application:

"Powered By Verified" Graphic Variants
Signup
Login
Verify
Apply
Access
AutoFill

2. Call POST /1-click.​

Call POST /1-click with the user's phone number:

POST /1-click Request Body
{
    phone: string // Example: "+12125550010"
}
Recency Requirement

You must call POST /1-click within 30 minutes of verifying the user's phone number (step 1). This is an important anti-fraud measure.

danger

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.

tip

You'll see in the endpoint reference for POST /1-click that it supports additional inputs including the user's email, birth date, and SSN4.

If you already have any of these, include them in the request body along with phone. (We don't recommend prompting for any of them yet if you don't already have them.)

Here's why: You'll see later in this guide that, if we can't source data for the user based on just their phone number, you'll need to ask the user for additional information (birth date and/or SSN4) and then make another API call. If for any reason you already have this information, you should include at this step so no further call will be necessary.

One of two things will happen:

  • Success: If we can source data based on just the phone number, the response body will contain a 1ClickEntity (see this example), keyed on identity, that contains the user's data and metadata about it. In this case, continue to step 5.
  • Error: Otherwise, the response body will contain an error with a Verified error code:
    • OCE011 indicates that we need additional information (the user's birth date and/or SSN4) to source data. → Continue to step 3
    • OCE013 indicates that Verified found no credentials for the user. → Fall back to a manual signup flow.(#6-if-necessary-prompt-user-for-additional-info)._
    • OCE017 indicates that Verified blocked the user because the risk score was too high. → Reject the user or flag them and fall back to a manual signup flow.

3. (if necessary) Prompt user for additional info.​

note

This step is necessary if step 2 doesn't succeed, which means we need more information (the user's birth date and/or SSN4) to uniquely identify the user. The response body of POST /1-click will be an error with error code OCE011.

Note that this error code, which is Verified specific, is data.errorCode in the error object, not code (which is a standard HTTP response status code).

We recommend using a numeric input (formatted as MM/DD/YYYY for birthday) that automatically submits when the user enters enough digits (8 for birth date and 4 for SSN4). (See the Birthday and SSN4 screens of our User Experience guide for full details.)

Birth Date Format

You'll need to pass the birth date to our API (in the request body of POST /1-click) in YYYY-MM-DD format, but you should collect it from the user in whatever form you think results in the best user experience for your use case.

Here are examples:

Numeric input, formatted as MM/DD/YYYY, and the green signup variant of the "powered by" graphic

Numeric input and the green signup variant of the "powered by" graphic

4. (if necessary) Call POST /1-click with additional info.​

note

This step is necessary if step 2 doesn't succeed, which means we need more information (the user's birth date and/or SSN4) to uniquely identify the user. The response body of POST /1-click will be an error with error code OCE011.

Note that this error code, which is Verified specific, is data.errorCode in the error object, not code (which is a standard HTTP response status code).

Call POST /1-click with the user's phone number and birth date or SSN4 (or both):

POST /1-click Request Body
{
    phone: string, // Example: "+12125550010"
    birthDate: string, // Example: "1989-08-01"
    ssn4: string // Example: "6789"
}
Sandbox Validation

In Sandbox, you need to do the following to pass validation:

  • If you use birthDate, use a value of "1989-08-01".
  • If you use ssn4, use a value of "6789".

If you use other values, you'll get the OCE012 error code, which indicates that there's a mismatch.

Recency Requirement

You must call POST /1-click within 30 minutes of verifying the user's phone number (step 1). This is an important anti-fraud measure.

One of two things should happen:

  • Success: If we can source data based on the phone number and birth date, the response body will be a 1ClickEntity (see this example), which contains the user's data and metadata about it. → Continue to step 5.
  • Error: Otherwise, the response body will contain an error with a Verified error code:
    • OCE012 indicates that one or more of the additional inputs you passed (the user's birth date and/or SSN4) mismatched. → Return to step 3.
    • OCE013 indicates that Verified found no credentials for the user. → Fall back to a manual signup flow.
    • OCE019 indicates that the maximum number of attempts has been reached for one or more of the additional inputs. → Fall back to a manual signup flow.

5. Prompt user to confirm their data.​

You must display the user's credential data to them and have them confirm it's correct. The credential data is contained in credentials in the 1ClickEntity from the API response. You don't need to display any metadata (contained in metadata in the 1ClickEntity) though you can choose to if it's relevant.

User Confirmation is a Requirement

You may not store a user's credential 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.

Benefits of Doing This
  1. Transparency: By displaying the user's data to them, you ensure they're aware of what data you've received about them.
  2. 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 recommend that you:

  1. Use a static display for view mode
  2. Use a form with autofilled inputs for edit mode
  3. 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 credentials of a given type (for example Address), 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 an input for that credential type.

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.

Mask Social Security Numbers

We require you to mask Social Security Numbers because they're particularly sensitive:

  • Mask the first 5 digits server side, so the client only displays the last 4 digits.
  • If you allow the user to edit the SSN, clear the entire value when they start editing, so they don't just edit the last 4 digits.

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

Possible Data Inaccuracies

The most common inaccuracy is an outdated address. We keep user addresses up to date as much as possible, but if the user has moved very recently, we may not yet have their current address.

Less commonly, a user may have an outdated name, if they've recently had it legally changed and we haven't yet updated it.

Some data points, like birth date and SSN, should never change, but it's still possible (in very rare cases) for these to be inaccurate. So, if having perfectly accurate data is crucial for your use case, we recommend that you have users confirm it.

Go Live!​

Request Approval​

When you're ready to go live, request approval for Production access:

  1. Go to the Brand Details page for your brand in the Verified Dashboard.
  2. Click the Sandbox tab in the upper right, and make sure your brand settings are synced. If they're not, click the Sync to Production button.
  3. Click the Production tab in the upper right, and click the Request Approval button under the API Keys section.
  4. Complete the steps listed in the dialog.
  5. Click the Submit Request button.

In step 4, you'll be asked to confirm the following:








important

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:

  1. Swap your Sandbox API key for your Production API key.
  2. Swap the Sandbox base URL for the Production base URL.

Then you'll be live with 1-Click Signup! ✅