Get Started with Verify API

Introduction

Add reliable and efficient security to web applications by authenticating users with one-time passcodes delivered through SMS or Voice Calls.


How It Works

Verification

Overview

Use the Verify API to create user Verifications that deliver a one time passcode (OTP) to a specified phone number through either SMS or a voice call. Each verification uses a simple, templated message, optimized for conversion, in which developers can optionally insert a Brand name of their choosing. The code returned by the recipient is then asserted against the Verification and is either verified or rejected.

Note: Brand can only be used if the Verification is sent from a phone number provisioned to your Voxology application.

Verification Status
  • pending // the initial status of a Verification upon creation. Verifications remain in pending until a code is verified, the maximum number of assert attempts is reached, or it times out.
  • verified // the correct code was asserted against this Verification.
  • failed // the maximum number of assert attempts was reached without successful verification.
  • timed-out // the time-to-live expired without successful verification.
  • canceled // the Verification was canceled using the Cancel Verification request
Verification // Example Object
{
  "verification_id": "ce66e293-c921-46ea-a085-e186f681d24c",
  "verify_no": "+15558701034",
  "api_no": "+15553246897",
  "channel": "sms",
  "brand": "Company Name",
  "status": "pending",
  "reason": null,
  "code_length": 6,
  "time_to_live": 10,
  "assert_attempts": 0,
  "created_on": "2024-01-01T00:00:00.000Z",
  "updated_on": "2024-01-01T00:00:00.000Z"
}

Channels

Overview

Verifications can be sent through either SMS or Voice. All calls and messages initiated through the Verify API have their service property set to verify. Use this to filter logs and view usage for the Verify API.

SMS

To send a OTP through SMS, set the channel property to "sms". All Verifications sent through SMS use a default, templated message.

  • Without Brand // “Your one time passcode is {code}”
  • With Brand // “{Brand}: Your one time passcode is {code}”

Voice

To send an OTP with a voice call, set the channel property to "voice". All Verifications sent through voice use a default text-to-speech message.

  • Without Brand // “Your one time passcode is {code}”
  • With Brand // “This is a verification call from {Brand}. Your one time passcode is {code}”

Assertion

Overview

Once a code has been returned by the authenticating user, it can be asserted against the Verification by ID. The Verify API will return either a verified or failed status in response to an assert request. Each Verification has a maximum of 3 assert attempts before its status changes to failed. Once the time-to-live on the Verification expires a code cannot be asserted.

Verification // Example Object
{
  "verification_id": "ce66e293-c921-46ea-a085-e186f681d24c",
  "status": "verified"
}

Getting Started

Get started with Verify API.

User Verification

Overview

This tutorial is a step-by-step guide to using the Verify API.

Prerequisites

Tutorial

1. Enable The Voxology Autoresponder

In order to use a branded message for your Verification, you must provision a unique phone number to your Voxology application. For help provisioning numbers, see our Provision Phone Number tutorial.

Note: to send Verifications through SMS using a unique number, the number must also be a Long Code registered to an approved 10DLC Campaign, a Toll-Free number verified for SMS, or an approved Short Code.

2. Initiate Verification

To start a new Verification, use the Initiate Verification request. In the request body, define the phone number to send the OTP to, the phone number to use as the sender, the channel to use, the Brand to include in the message, the length of the code and the time-to-live for the Verification.

Initiate Verification // Example Request
curl -X POST \
 https://api.voxolo.gy/v1/Verifications \
 -H 'Cache-Control: no-cache' \
 -H 'Content-Type: application/json' \
 -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
   "verify_no": "+15558701034",
   "api_no": "+15553246897",
   "channel": "sms",
   "brand": "Company Name",
   "code_length": 6
   "time_to_live": 10
}'

3. Assert Verification

Once a OTP has been returned by the recipient, use the Assert Verification request to either verify or fail the authenticating user. Verifications can be asserted 3 times before the status updates to failed. Only Verifications with status pending can be asserted.

Assert Verification // Example Request
curl -X POST \
 https://api.voxolo.gy/v1/Verifications/ce66e293-c921-46ea-a085-e186f681d24c/Assert \
 -H 'Cache-Control: no-cache' \
 -H 'Content-Type: application/json' \
 -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
   "code": "639469"
}'

4. Cancel Verification

If you wish to cancel a Verification while it’s still pending, use the Cancel Verification request. Canceling a verification updates its status to canceled.

curl -X DELETE \
 https://api.voxolo.gy/v1/Verifications/ce66e293-c921-46ea-a085-e186f681d24c \
 -H 'Cache-Control: no-cache' \
 -H 'Content-Type: application/json' \
 -H 'X-API-Key: YOUR_API_KEY'

Congratulations! You can now verify users in your own application.