Getting Started with Verify API

Verify allows you to confirm a user's phone number by sending a One-Time Password (OTP) through multiple channels like SMS, email, voice, and WhatsApp. You can define a workflow to control which channels are used and in what order.

This guide shows you how to call the Verify API synchronously, using a workflow that first attempts SMS delivery and then falls back to a voice call if SMS fails. You will also learn how to customize the OTP code length and timeouts between steps.

Prerequisites

This guide assumess that:

• You have a Vonage account. If not, you can create one for free here.
• You have cURL installed in your system.

Create a New Application

To get started, we need to create a new application. This application will contain the credentials required to authenticate the API calls. Follow these steps:

1. Go to the Vonage Application Dashboard.
2. Click Create a new application.
3. In the Name field, enter a name for your application.
4. In the Authentication section, click Generate public and private key to generate a new key pair. A private key file (.key) will be automatically downloaded. Save this file securely, as it is required for authenticating your API calls.
5. Now go to the Capabilities section. Since we don't want to receive asynchronous status updates, you can leave the Verify capability switched off.
6. Finally, click the Generate new application button to complete the creation process.

After the application is created, copy the Application ID displayed on the dashboard. You will need this Application ID along with the private key file to generate JWTs for authenticating API requests.

Verify End-Users with OTP

To verify end-users using a One-Time-Password (OTP), follow these two steps:

1. Request a verification code. The end-user will receive the code through one of the channels specified in your API call.
2. Check the supplied verification code. A second API call will validate the code introduced by the user.

Request a Verification Code

According to the API specification, the first step is to send a

Let’s take a look at the headers and body of the request to better understand the API call.

If the request is successful, you will receive a 200 Ok response containing a request_id in the body:

{
   "request_id":"3b4363c9-1234-567a-90ab-c45a134561"
}

At the same time, the end-user should receive an SMS containing a 5-digit verification code. If the user does not complete the verification within 30 seconds (as defined by channel_timeout), they will automatically receive a voice call where the code is read aloud.

You will need both the request_id and the code entered by the user to complete the verification in the next step.

Check the Supplied Verification Code

Once the end-user receives the code, you must send a

Request Headers:

Request body:

If the request is successful, you will receive a 200 OK response informing that the verification process has been completed:

{
   "request_id":"3b4363c9-1234-567a-90ab-c45a134561",
   "status":"completed"
}

Conclusion

In this guide, you learned how to implement end-user verification using the Verify API with a multi-channel configuration: starting with SMS and falling back to Voice if needed.

The cURL examples provided here are solely for learning purposes. In a real implementation, you should integrate Verify directly into your backend, using your preferred programming language.

What's next?

Now that you understand how the Verify API works and how powerful the multi-channel approach is, explore the different supported channels you can use in your verification workflow.

Improve your verification process by implementing Silent Authentication, which allows you to verify users over mobile traffic without requiring them to enter an OTP.

Finally, don’t forget to check the API specification, where you'll find more useful parameters to get the most out of the Verify API.