Blog/

Multichannel data verification via API

11.03.2025

In today's world, account security and data authenticity play a crucial role. Services strive to verify the accuracy of information, while users aim to protect their data.

When registering or logging into an account, users provide their contact details - phone number or email. Verification is required to ensure that the information is entered correctly and belongs to a real person.

Data verification is important both for the user and the service itself. For the customer, verification means additional security and convenience. It helps protect personal data and simplifies access recovery. For businesses, it serves as a way to keep the customer database accurate by removing invalid contacts and preventing mass registrations.

The Zadarma API interface provides a solution for multichannel user verification - the method /v1/verify/.

Currently, the method supports 4 channels:

SMS - an SMS message with a verification code will be sent to the recipient's number,
A call with a code (call_code) - a call is made to the recipient's number, during which the verification code is announced,
A call with instructions (call_button) - a call is made to the recipient's number, during which the user must follow the instructions provided in the audio files and press the "1" button to confirm,
Email - an email with a verification code is sent to the specified email address.

The API interface is completely free and available on all Zadarma accounts.

How to start working with the Zadarma API?

The best option to start using the Zadarma API is to install our library, written in PHP: github.com/zadarma/user-api-v1. It contains a detailed guide on how to install and configure the API client.

Interaction with the method /v1/verify/

In this section, we will provide request examples and response checks for each of the 4 channels.

SMS channel

Sending a verification code via SMS. It can be used for verifying numbers during registration or for two-factor authentication. Sending an SMS is paid, therefore, the user’s API account must have a positive balance.

Example of sending a verification request via the SMS channel:



$zd = new \Zadarma_API\Client('key_from_user_panel', 'secret_code_from_user_panel');
$answer = $zd->call('/v1/verify/', [
   'channel' => 'sms',
   'to' => '+19999999999'
], 'POST');
// decode string {"status":"success","request_id":"N2QreWpjS25mR3EvOW8rdGNHdFF2aVE9"} to the php array
$answerDecoded = json_decode($answer, true);
// $answerDecoded equals ['status' => 'success', 'request_id' => 'N2QreWpjS25mR3EvOW8rdGNHdFF2aVE9']

Explanation of the request: an SMS with an automatically generated code will be sent to the 'to' number. The default template will be used for the SMS, with the user's account language and the SenderID "Teamsale." If you need to use a custom template, a different language, a predefined code, or a registered SenderID, you can use additional parameters in the method (template_id, language, code и caller_id accordingly).

To verify the correctness of the code sent via SMS, you need to send a request in the following format:


$zd = new \Zadarma_API\Client('key_from_user_panel', 'secret_code_from_user_panel');
$answer = $zd->call('/v1/verify/check', 
   'request_id' => 'N2QreWpjS25mR3EvOW8rdGNHdFF2aVE9',
   'code' => '956305'
], 'POST');
// decode string {"status":"success","message":"Code is correct"} to the php array
$answerDecoded = json_decode($answer, true);
// $answerDecoded equals ['status' => 'success', 'message' => 'Code is correct']

call_code channel

When selecting this channel, a call is made to the recipient's number, during which the code is announced. This is an alternative method for number verification. It is suitable for verifying landline numbers or cases where SMS is unavailable.

To use this channel, the following is required:

The presence of a phone number in the Zadarma system.
Positive account balance.

Example of sending a verification request via the channel call_code:



$zd = new \Zadarma_API\Client('key_from_user_panel', 'secret_code_from_user_panel');
$answer = $zd->call('/v1/verify/', [
   'channel' => 'call_code',
   'to' => '+19999999999'
], 'POST');
// decode string {"status":"success","request_id":"N2QreWpjS25mR3EvOW8rdGNHdFF2aVE9"} to the php array
$answerDecoded = json_decode($answer, true);
// $answerDecoded equals ['status' => 'success', 'request_id' => 'N2QreWpjS25mR3EvOW8rdGNHdFF2aVE9']

Explanation of the request: a call is made to the 'to' number, and once the receiver is picked up, the automatically generated code is announced twice. By default, the message is spoken in the language of the user’s account. If a different language is needed, specify the desired language in the parameter language.

Important: If more than one virtual number is connected to the account, the from parameter should include the number in E.164 format, from which the call will be made.

Verification of the code's correctness:


$zd = new \Zadarma_API\Client('key_from_user_panel', 'secret_code_from_user_panel');
$answer = $zd->call('/v1/verify/check', [
   'request_id' => 'N2QreWpjS25mR3EvOW8rdGNHdFF2aVE9',
   'code' => '249376'
], 'POST');
// decode string {"status":"success","message":"Code is correct"} to the php array
$answerDecoded = json_decode($answer, true);
// $answerDecoded equals ['status' => 'success', 'message' => 'Code is correct']

call_button channel

This channel is intended for cases where the user must be clearly informed about what is being confirmed before any action is taken. Instead of simply providing the code, the system calls the user and delivers a voice message with instructions. To confirm the request, the subscriber must press a button "1".

To use this channel, the following is required:

The presence of a phone number in the Zadarma system
Enabled PBX.
In the event notifications a URL for notifications must be specified, and the webhook NOTIFY_OUT_END must be enabled.
Positive account balance.

Example of sending a verification request via the call_button channel:


$zd = new \Zadarma_API\Client('key_from_user_panel', 'secret_code_from_user_panel');
$answer = $zd->call('/v1/verify/', [
   'channel' => 'call_button',
   'to' => '+19999999999',
   'greeting_sound_id' => '657c2c822fb364c1d201f685',
   'button_1_sound_id' => '6718bc2af7cd712b0e0a96f6',
   'fallback_sound_id' => '6718bd57e2cc3072e20c0ba6'
], 'POST');
// decode string {"status":"success"} to the php array
$answerDecoded = json_decode($answer, true);
// $answerDecoded equals ['status' => 'success']

Explanation of the request: a call is made to the 'to' number, and after the call is picked up, a file from the ‘greeting_sound_id’ parameter is played. If the user confirms the action, they press the "1" button and hear the file from the 'button_1_sound_id' parameter. If the user doesn't press the "1" button, but presses another button or takes no action, the file from the 'fallback_sound_id' parameter will be played.

Important: the transmission of audio files for this method is mandatory. To manage the audio files used in the parameters greeting_sound_id, button_1_sound_id and fallback_sound_id, use the API methods available in the section /v1/pbx/ivr/sounds/*.

If more than one virtual number is connected on the account, the from parameter, in E.164 format, must include the number from which the call will be made.

Verification of the code's correctness:

The result of processing the request through the call_button channel is sent to the URL specified in the integration “Notifications” in the personal account, with $_POST format data:



(
    [event] => NOTIFY_END
    [call_start] => 2024-10-23 16:00:47
    [pbx_call_id] => out_0e7d449cac2f0a3ce54919e91cd999194e8f2d97
    [caller_id] => 0999999999
    [called_did] => 0
    [internal] => 100
    [last_internal] => 100
    [duration] => 3
    [status_code] => 16
    [is_recorded] => 0
    [calltype] => callback_leg1
    [callback_dtmf] => 1
    [disposition] => answered
)

In the callback_dtmf the button that was pressed is passed, or an empty value if the user pressed nothing.

In the disposition there will be information about whether the user answered the call. "Answered" means the call was answered, while "cancel" means it was not answered.

In the caller_id the number to which the call was made will be specified.

A simple way to check if the request was successfully executed and the user confirmed the request is to verify that $_POST['callback_dtmf'] == '1'

Email channel

When using this channel, an email with a verification code is sent. This method can be used for registration confirmation, two-factor authentication, or password recovery.

To use this channel, the following is required:

an active integration with Teamsale
configured email synchronization

Example of sending a request via the email channel:


$zd = new \Zadarma_API\Client('key_from_user_panel', 'secret_code_from_user_panel');
$answer = $zd->call('/v1/verify/', [
   'channel' => 'email',
   'to' => 'test-email@zadarma.com'
], 'POST');
// decode string {"status":"success","request_id":"N2RLeGlzcWpmR3EvOW8rdGNHaFN1U1k9"} to the php array
$answerDecoded = json_decode($answer, true);
// $answerDecoded equals ['status' => 'success', 'request_id' => 'N2RLeGlzcWpmR3EvOW8rdGNHaFN1U1k9']

Explanation of the request: An email with an automatically generated code is sent to the 'to' address. The default subject and template are used, and the text will be in the language of the user's account. If a different language, custom subject, or email body is needed, use the additional parameters language, email_subject and email_body to pass the desired values.

Important: if more than one email integration is activated on the account, the sender's email address must be provided in the from parameter.

If you are providing your own email body text, you need to include the line "code" for the automatic insertion of the verification code.

Verification of the code's correctness:



$zd = new \Zadarma_API\Client('key_from_user_panel', 'secret_code_from_user_panel');
$answer = $zd->call('/v1/verify/check', [
   'request_id' => 'N2RLeGlzcWpmR3EvOW8rdGNHaFN1U1k9',
   'code' => '7348295'
], 'POST');
// decode string {"status":"success","message":"Code is correct"} to the php array
$answerDecoded = json_decode($answer, true);
// $answerDecoded equals ['status' => 'success', 'message' => 'Code is correct']

Implement modern verification methods to improve the security of the service while maintaining its convenience and stability.