Verify Workflow

A Workflow defines the sequence of actions that Vonage uses to reach the end-user you want to verify with a PIN code. You can customize your own workflow by specifying which channels to use and in what order, enabling verification messages to be sent to multiple phone numbers, email addresses, and more.

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.

curl -X POST "https://api.nexmo.com/v2/verify" \
    -H "Authorization: Bearer $JWT" \
    -H 'Content-Type: application/json' \
    -d $'{
        "brand": "TestVerify",
        "locale": "es-es",
        "code_length": 4,
        "channel_timeout": 300,
        "workflow": [
        {
            "channel": "sms",
            "to": "'$PHONE_NUMBER'"
        },
        {
            "channel": "voice",
            "to": "'$PHONE_NUMBER'"
        }
    ]
}'

Check the API specification for a full list of available parameters and detailed descriptions.

Supported Channels

Verify supports multiple channels to deliver One-Time Passwords (OTPs) based on user preferences and regional connectivity. Here’s an overview of each supported channel:

Silent Authentication

Silent Authentication allows you to verify end-users without requiring them to manually enter an OTP. It works by leveraging mobile network data in the background, providing a better user experience. It's ideal fo reducing drop-offs during sign-up or login flows.

RCS

As an enhancement of the SMS channel, RCS enables message delivery over Wi-Fi or mobile data to default messaging apps on Android and iPhone.

RCS stands out as a superior alternative to SMS due to its support for brand validation and its low delivery latency. To utilize the RCS channel, an RCS Agent or Sender ID is required.

Currently, RCS is available in a limited number of countries and on compatible devices, with plans for future expansion.

SMS

SMS is the most popular and widely adopted channel for two-factor authentication (2FA).

It offers broad reach since almost everyone can receive text messages, and onboarding is seamless. In fact, Google found that SMS 2FA helped block:

• 100% of automated bots
• 96% of bulk phishing attacks
• 76% of targeted attacks

Due to its reliability and ubiquity, SMS is often the first channel attempted in a Verify workflow.

WhatsApp

WhatsApp is a great channel for two-factor authentication thanks to its global popularity and the ability to deliver messages over WiFi, making it particularly valuable in areas with limited mobile coverage.

Adding WhatsApp as a secondary channel can significantly improve your overall verification conversion rates.

To use Verify API 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 installed, Verify can automatically detect this and fallback to another channel.

Voice

Voice verification is a powerful backup to SMS, especially in regions where:

• SMS delivery is unreliable.
• Local regulations impose restrictions or require pre-registration for SMS traffic.

With voice calls, the OTP is delivered via an automated phone call, ensuring that users in less accessible regions can still complete their verification process reliably.

Email

Email can also be used to deliver OTPs, making it a strong alternative to mobile-based channels.

It is especially useful:

• During periods of network congestion.
• For users who prefer receiving verifications through their email account.