Verify Migration Guide

The following guide will help you migrate from Verify Legacy to Verify. To do this, you need to update your endpoint URLs to call the new version and modify your application settings; you are not required to fill any pre-registration form in order to start using Verify.

Summary

The Vonage Verify API is a service that allows developers to implement two-factor authentication (2FA) to protect against fraud and ensure user authenticity. Vonage offers two versions of this API: Legacy and the current Verify. While both versions serve the same primary function, there are significant differences in their features, functionalities, and usage.

Major Differences

• Flexibility and Customization: Verify now offers more flexible workflow creation and enhanced customization options such as a more feature-rich Custom Templates management system compared to Legacy.
• Channel Support: Verify now includes additional support for verification through various new channels like Silent Auth, WhatsApp and Email, while Legacy is limited to SMS and voice.
• Security Features: Verify now includes improved security features and compliance with the latest standards.
• Error Handling: Verify now provides more detailed error messages and improved handling, such as well as more advanced rate limiting and automatic retry mechanisms.
• API Design and Usability: Verify now has a more user-friendly design and easier integration capabilities with modern applications such as synchronous and asynchronous options.

Feature Comparison

API Calls

Asynchronous mode has been introduced in Verify, allowing you to receive messages and call statutes by webhook, receiving both event (in the case of whatsapp_interactive) and summary callbacks. You can also use it synchronously with redirect_url and check_url.

You must configure your webhooks for Verify callbacks in the Application section of the Customer Dashboard:

Further documentation on webhooks can be found here.

Endpoints

All Verify API calls need to be updated to use the new endpoint:

Workflows

Verify provides you with the flexibility to define your own workflow, as opposed to the fixed workflows of Legacy. You can specify any combination of supporting channels of your choice in the workflow, to a maximum of three channels.

Further documentation on workflows can be found here.

Channels

New channels are now available in Verify:

• SMS
• Voice (formerly TTS in Legacy)
• WhatsApp
• Email
• Silent Authentication

For more detailed information on these channels refer to the API Specification.

Documentation specific to silent authentication can be found here.

Summary Callbacks

Callbacks are returned to your webhook with the status of the event, corresponding request_id & channel. The following sequence diagrams show how this works when using a single channel, or using multiple channels in your workflow.

Single Channel

Multiple Channels

Response Codes

In addition to changing your endpoints, your applications also need to be updated to understand the response codes received when using Verify:

Request Cancellation

Templates

PSD2 Compliance

Search Verification Request

Fraud Management

Verify Sequence Diagrams

Verify Flow

Verify Request with Summary Callbacks

Silent Authentication Sequence Diagram