Integration Guide
This Integration Guide will help you fully integrate 1-Click Signup into your application.
| Time to Integrate | 1 hour |
|---|---|
| Time to Test and Deploy | 1 day |
| Steps Required | Make API call(s), send SMS |
Setup
1. Access Dashboard.
Someone at your company may have already created an account for you, in which case you would have received an email invite. Check for this before creating a new account.
Detailed Steps
a. Enter your email and click the 1-Click Login button.
We'll send you a verification code by email.
Use your work email. We use AI magic to autofill brand information based on your email domain, so you don't have to manually enter it!
b. Complete the verification step.
Click the verification button in the email or enter the verification code. We'll automatically log you in. It's a 1-click experience, as promised!
c. (if necessary) Confirm your company name.
If you're creating the Dashboard account for your company, we'll ask you to confirm your company name. If someone on your team has already created your account, you won't need to do this.
If your account doesn't have a brand yet, we'll automatically create one for you and take you to its Brand Details page.
Your company account can have one or more brands. Generally, you'll only need one brand, but there are some cases where it's helpful to use multiple. For example:
- If you have multiple products: If you have products that go by different names, it can be useful to create different brands to help users know which product they're using 1-Click Signup for — and to help your team track metrics specific to that product.
- If you want to try different brand settings: If you want to change brand settings without affecting your existing implementation (even in Sandbox), you can duplicate your brand and configure different settings on the new brand.
d. (optional) Invite team members.
Invite your team members to join your Dashboard account.
2. Configure brand settings.
On the Brand Details page in the Dashboard, you can configure settings for your brand.
The most important brand setting is integration type, which affects how you integrate 1-Click Signup.
How to Choose Integration Type
You can always start with one integration type and change it later.
There are three options for integration type:
| Integration Type | User Interface | Phone Verification Code | SMS | Description | Best If... |
|---|---|---|---|---|---|
| Hosted | Hosted by Verified | Generated by Verified | Sent by You | Use Verified's UI and Verified's verification code | You want the quickest implementation |
| Semi-Hosted | Hosted by You | Generated by Verified | Sent by You | Use your own UI but Verified's verification code | You don't already verify users' phone numbers |
| Non-Hosted Recommended | Hosted by You | Generated by You | Sent by You | Use your own UI and your own verification code | You do already verify users' phone numbers |
Non-Hosted is the most common integration type and the one we recommend. It allows you to make 1 API call and receive user data directly in the response body. It's the simplest way to integrate 1-Click Signup, as long as you already verify user's phone numbers. If you don't already do this, Semi-Hosted or Hosted may be a better option.
1-Click Signup is based on a phone number and requires verifying that phone number via a verification code sent by SMS. For the Hosted and Semi-Hosted integration types, we generate that code for you (and check user input against it). For the Non-Hosted integration type, you generate your own code (and check user input against it).
But for all integration types, you send the SMS with the verification code. Verified never sends SMS for you. This is unfortunately necessary due to the strictness of US regulations around SMS. It protects your company and ours for you to send the SMS, so that the user receives the SMS from the company they're directly interacting with. (It also helps avoid confusion, in case you already send SMS for other purposes, so that all SMS for your company come from numbers you control.)
Determining which option is best for you is simple. Just answer these questions:
a. Do you want to use Verified's UI or your own?
Using Verified's UI is the easiest option, but using your own UI is more white label. You can always start with Verified's UI — for example to quickly try out 1-Click Signup — and then switch to your own UI later.
- Verified's UI → Select Hosted in the Dashboard, and select the Hosted tab below
- Your own UI → Continue to question b...
b. Do you want to use Verified's phone verification code or your own?
If you don't already verify users' phone numbers, it's easiest to use a phone verification code generated by Verified. But if you already verify users' phone numbers and want to use your existing solution for that, you can use your own phone verification code.
- Verified's phone verification code → Select Semi-Hosted in the Dashboard, and select the Semi-Hosted tab below
- Your own phone verification code → Select Non-Hosted in the Dashboard, and select the Non-Hosted tab below
Choose an integration type, and then select the corresponding tab below. That way, the rest of these Verified Docs will display only content relevant to your integration type.
- Hosted
- Semi-Hosted
- Non-Hosted
Another important brand setting is default credential requests, which determines what user data Verified will try to source for you.
- A credential is a piece of identity data about a user (like a first name or address).
- A credential request is how you ask Verified for a particular credential. It encodes what type of data you're asking for, whether it's required or optional, whether multiple values should be returned, etc. See the
CredentialRequesttype for full details.
When you create a new brand, the Dashboard starts you off with standard default credential requests to provide you with a helpful starting point. Edit these to reflect the user data you'd like Verified to source.
The default credential requests are called default because they apply if you don't include the optional credentialRequests attribute in the request body of POST /1-click (which you call in step 2 of Integration below).
If you do include credentialRequests in the request body of POST /1-click, they will override the default credential requests defined in the Dashboard. We don't recommend doing this unless your use case requires you to dynamically change credential requests on a per API call basis. Note that if you include credentialRequests, it must be an array of CredentialRequest objects.
Integration
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.
- Hosted
- Semi-Hosted
- Non-Hosted
With the Hosted tab active above, your brand's integration type setting should be set to Hosted in the Dashboard. See Determine integration type if you need help deciding which type is right for you.
Here is the Sequence Diagram for the Hosted integration type:
1. Prompt user for phone number.
To start 1-Click Signup for a user (using the Hosted integration type), you'll need their phone number.
We recommend using a form with a phone number input that automatically submits when the user enters 10 digits. See our Demo for an example of this.
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 +10123456789.
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.
You'll also need to:
Here's a full example:
Hooli uses a phone number input, and they include a gray variant of the "powered by" graphic and Verified legal language.
a. Include "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 Signup 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 birth date input or a button.
We provide several variants of the graphic, in both SVG and PNG format. Choose the one you prefer and that best fits the background color of your application.
"Powered By Verified" Graphics
Green:
Black:
Gray:
White:
b. Include Verified legal language.
Regulations require that users give informed consent, so you must our legal 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}, you agree to receive an SMS to create a Verified account for 1-Click Signup at{Brand Name}and other supported sites, and you agree to Verified's Terms of Use.
- 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, we recommend using "entering your phone number".
- If you use a Continue button, we recommend using "clicking Continue".
- Replace
{Brand Name}with your brand name. - Link "Terms of Use" to https://verified.inc/legal#terms-of-use and make it a different color than the rest of the text, underlined, or both (so the user knows it's a link).
2. Call POST /1-click.
Call POST /1-click with the user's phone number.
Never use Verified API keys client side. Only use them server side. Verified API keys allow you to source sensitive data about user, so you must keep them secure. This is why we require that you get clear user consent before calling our API and why we review your integration in Sandbox before giving you Production access. See our go live checklist for details.
The response body will contain url and code, which you'll use in the following steps.
3. Send SMS to user.
Send an SMS to the user with code from the response body of POST /1-click.
We recommend using this language, where {Brand Name} is your brand name:
Enter this code to verify for
{Brand Name}:code
For example:
Enter this code to verify for Hooli: 123456
You can also optionally use code to construct a verification link. For example, if url is a link to your application, you could:
- Append
codeas a URL parameter tourl:{url}?code={code}. - Set up your application to parse
codefrom the URL.
Then, you could include language like this in the SMS:
Click this link to verify for
{Brand Name}:{url}?code={code}
For example, if the url for the Hooli brand is https://hooli.com/verified:
Click this link to verify for Hooli: https://hooli.com/verified?code=123456
Our test user's phone numbers aren't valid phone numbers, so sending SMS to them won't work. You can simulate the SMS step by using the static verification code (111111), but we recommend instead using your own phone number(s) for testing, so you can send yourself real SMS messages.
4. Redirect user.
Redirect the user to url from the response body of POST /1-click. (If the user is in your mobile app, open a webview to url.)
This url is a link to our web app, where we'll prompt the user to:
- Enter their verification code
- (if necessary) Enter their birth date
- Confirm their data and agree to share it with your brand
When the user has completed this, we'll redirect them back to you.
5. Parse identityUuid from URL.
When we redirect the user back to you, we'll include on the redirect URL an identityUuid URL parameter, whose value is a UUID.
For example, if your redirect URL is https://hooli.com/verified, we will send the user to:
https://hooli.com/verified?identityUuid=47e34f9c-a18b-4e67-a202-3f5389d06c08
We'll redirect the user to the default redirect URL set for your brand in the Dashboard, unless you overrode that default by including redirectUrl in the request body of POST /1-click.
Using http://localhost as the redirect URL directly will not work due to security restrictions.
For local testing, consider using a tunneling service like ngrok or Localtunnel to expose your local development server to a publicly accessible URL.
Parse the value of the identityUuid URL parameter from the redirect URL. You'll use this UUID in the next step. (If the user is in your mobile app, you can now close the webview you opened in the previous step.)
6. Call GET /1-click.
Call GET /1-click/{identityUuid} with the value of the identityUuid URL parameter.
The response body will be a 1ClickEntity (see this example), which contains the user's data and metadata about it. You can use this data however you like to create a new account for the user!
Go Live!
When you're ready to go live:
- Go to the Brand Details page for your brand in the Verified Dashboard.
- Click the Production tab in the upper right.
- Click the Request Approval button under the API Keys section.
- Complete the steps listed in the dialog that appears:
- Click the Submit Request button.
In step 4, you'll be asked to confirm the following:
We will 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.
Just swap your Sandbox API key for a Production API key, and you'll be live with 1-Click Signup!