Verify API Technical Details

The Verify product is our next generation two-factor authentication (2FA) product. It has the benefits of more channels including over-the-top (OTT) channels like WhatsApp and more traditional channels like SMS, Voice, and Email.

We added event and summary callbacks that open the door to a multitude of integration and customization opportunities. To start, you can configure a webhook to ingest summary callbacks that details which channels successfully converted and which did not. Event callbacks allow us to offer unique end-users experiences such as the WhatsApp Codeless channel. Here an end-user can push a button within the WhatsApp message in order to authenticate, then we send an event callback to the backend to instruct you on how to proceed with the end-user experience.

Authentication

In addition to basic authentication, authentication in Verify can be done through JWTs. These can be generated via the Vonage Server SDKs, or through the online tool. For more information on authentication using JWTs, see the Authentication guide.

To use Silent Authentication, you must use JWT Authentication in your requests otherwise you will not receive the necessary webhooks to implement it.

Workflows

Workflows are a sequence of actions that Vonage use to reach the user you wish to verify with a PIN code. In Verify (Legacy), those workflows were pre-configured and you could choose the best one for your use case. In Verify, you can define your own workflow that works best for you. Specify which channels you want to use and what order to use them in, and send verification messages to multiple phone numbers, email addresses, etc.

The workflow is configured using an array in your verification request. The first channel in the list is used first; if the message is not successfully converted then the next channel in the list will be used. In the example below, SMS would be tried first. If that fails to convert, Voice would be used next.

It is important to note that if you want to use the Silent Authentication channel, it must be the first workflow

locale - Specify the language you want the 2FA to be sent in - it must be in ISO639-1 format.
channel_timeout - Specify the wait time for the verification code to be delivered and entered by the user, to a maximum of 900 seconds. This used to be called next_event_wait in Verify Legacy.
code_length - Specify how long the code should be - can be between 4 and 10 digits.

Callbacks

The use of callbacks has been enabled in Verify, so you can now listen for an update via the callback and be notified if a response from the user comes in. To configure your callbacks, navigate to your application in the Vonage dashboard. Go to Capabilities and enable Verify V2 to enter your callback URL.

Verification Channels

SMS

SMS is the most popular channel for two-factor authentication (2FA). That's because most people can receive text messages and onboarding is seamless. Plus, SMS 2FA works: Google found that SMS 2FA helped block "100% of automated bots, 96% of bulk phishing attacks, and 76% of targeted attacks."

WhatsApp is a great channel for two-factor authentication because of its popularity around the world and delivery of messages only requires a WiFi connection. Adding WhatsApp to supplement SMS can improve your overall conversion rates.

To use Vonage Verify with WhatsApp, you must have your own WhatsApp Business Account (WABA). To create a WABA, navigate to the Social Channels section of the Developer Dashboard and follow the instructions under WhatsApp.

If a user does not have WhatsApp, Verify is able to detect this and can use another channel as a fallback.

For non-managed accounts, please contact Sales in order to configure Verify to use your company’s WhatsApp Business Account. For managed accounts, please reach out to your dedicated account manager.

Voice

Voice is a great backup to SMS for two-factor authentication, especially in geographies where it’s difficult to terminate SMS or if the local regulations require lengthy SMS pre-registration processes.

Email

One-time Passwords sent to email are also a good alternative to the channels mentioned above, especially in the instance of network congestion at the mobile operator level.

Our email solution supports domain registration. If you plan to scale email verification to high volumes with Verify and you are a non-managed customer, please contact Sales in order to get your account configured properly. For managed accounts, please contact your dedicated account manager.

Verify Sequence Diagram

Verify Request with Summary Callbacks

Verify V2 Request with Summary Callbacks

You can view the Verify API Reference here.