Skip to main content

API Integration

Time to Complete1-2 hours
Time to Test and Deploy2-4 hours
Skills RequiredMake API calls, build UX
tip

Complete the 1-Click Verify 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.​

To start 1-Click Verify for a user, you'll need their phone number.

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.

We recommend using a phone number input that auto submits when the user enters 10 digits. (See the Phone screen of the 1-Click Signup User Experience guide for full details.)

You'll also need to include this SMS consent language:

I authorize Verified to send me SMS verification texts at the number provided. Msg & Data rates may apply.

  • 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).
  • Make this visible to the user, somewhere on the page, before you call the Verified API.

See our Demo for an example of this.

2. Start verification flow.​

Call POST /1-click/verifications with the user's phone number, setting channel to sms:

POST /1-click/verifications Request Body Example
{
    "channel": "sms"
}
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.

The response body will contain a uuid that you'll use in the next step:

POST /1-click/verifications Response Body Example
{
    "uuid": "f5251850-496c-48cf-a4bd-d9d5ace22689",
    "phone": "+12125550010",
    "channel": "sms",
    "status": "pending",
    "createdAt": 1760053695000,
    "expiresAt": 1760053995000,
    "attemptsRemaining": 3
}

3. Deliver verification message.​

Call POST /1-click/verifications/{uuid}/deliver with the uuid from the previous step.

This will trigger Verified to send a verification SMS to the user's phone number. The response body will indicate that the messaging is being sent:

POST /1-click/verifications/{uuid}/deliver Response Body Example
{
    "uuid": "f5251850-496c-48cf-a4bd-d9d5ace22689",
    "channel": "sms",
    "status": "sending"
}

4. Prompt user for verification code.​

We recommend using a 6 separate single digit inputs that auto submit when the user enters 6 digits. (See the Verification Code screen of the 1-Click Signup User Experience guide for full details.)

5. Verify verification code.​

Call POST /1-click/verifications/{uuid}/verify with the uuid from the previous steps, including what the user entered in the previous step as code:

POST /1-click/verifications/{uuid}/verify Request Body Example
{
    "code": "111111"
}

This will trigger Verified to check the user's input against the verification code for this verification flow. The response body will indicate whether or not this check succeeds in the verified attribute:

POST /1-click/verifications/{uuid}/verify Response Body Example
{
    "uuid": "f5251850-496c-48cf-a4bd-d9d5ace22689",
    "phone": "+12125550010",
    "verifiedAt": 1760053705000,
    "attemptsRemaining": 2,
    "verified": true
}

6. (optional) Retrieve verification details.​

The verification details are included in the response body of the previous step. But if you ever want to retrieve these details again, you can do so by calling GET /1-click/verifications/{uuid} with the uuid from the previous steps.

The response body will contain the 1ClickVerificationEntity:

GET /1-click/verifications Response Body Example
{
    "uuid": "f5251850-496c-48cf-a4bd-d9d5ace22689",
    "phone": "+12125550010",
    "channel": "sms",
    "status": "verified",
    "createdAt": 1760053695000,
    "expiresAt": 1760053995000,
    "verifiedAt": 1760053705000
}

Handle Errors​

To ensure your integration is robust, handle all the 1-Click Verify errors. Most errors should be handled simply by starting a new 1-Click Verify flow.

Go Live!​

When you're ready to go live, you made need to request approval for Production access, depending on how you're using other Verified products:

  1. Go to the Brand Details page for your brand in the Verified Dashboard.
  2. Click the Production tab in the upper right, and make sure your brand settings are configured as you intend them to be.
  3. Click the Request Approval button under the API Keys section.
  4. Complete the steps listed in the dialog.
  5. Click the Submit Request button.

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 Verify! ✅