Verify a user

Using the Verify API, the workflow to confirm that your user can be contacted at a specific phone number is:

Participant Your server Participant Nexmo Participant User phone Your server-> Nexmo: 1. Send a phone verification code Nexmo-->Your server: Receive `request_id` Nexmo->User phone: 2. User receives code on \ntheir phone via a text \nmessage or text-to-speech User phone->Your server: 3. User enters verification code Your server->Nexmo: 4. check the phone verification \ncode and `request_id`
  1. Send a phone verification code and receive request_id from Nexmo
  2. User receives code on their phone via a text message or text-to-speech
  3. User enters verification code via a mechanism you provide, usually a form
  4. You check the phone verification code with Nexmo using code and request_id

You can optionally cancel a phone verification request or trigger the next verification process to advance from an SMS message verification to a text-to-speech verification.

Send a phone verification code

Once you have collected a user's phone number, you can start the verification process by sending an API request to Nexmo with the user's phone number.

curl "https://api.nexmo.com/verify/json?api_key=API_KEY&api_secret=API_SECRET&number=447700900000&brand=MyApp"
import com.nexmo.client.NexmoClient;
import com.nexmo.client.auth.AuthMethod;
import com.nexmo.client.verify.VerifyResult;

AuthMethod auth = new TokenAuthMethod(API_KEY, API_SECRET);
NexmoClient client = new NexmoClient(auth);
VerifyResult request = client.getVerifyClient().verify(TO_NUMBER, "MyApp");
<?php
$client = new Nexmo\Client(new Nexmo\Client\Credentials\Basic(API_KEY, API_SECRET));
$verification = $client->verify()->start([
    'number' => '447700900000',
    'brand'  => 'My App'
]);
import nexmo

client = nexmo.Client(key=api_key, secret=api_secret)
verify_resp = client.start_verification(number='447700900000', brand='MyApp')
require 'nexmo'

client = Nexmo::Client.new(api_key: API_KEY, api_secret: API_SECRET)

client.verify.request(number: '447700900000', brand: 'MyApp')

The API will return an request_id. This is used in subsequent API calls.

Check phone verification code

Your application should now show a form to allow the user to enter the PIN they have received. Once you have received the PIN, you should send it back to Nexmo along with the request_id from the first step. The API will tell you whether it is correct.

curl "https://api.nexmo.com/verify/check/json?api_key=API_KEY&api_secret=API_SECRET&request_id=REQUEST_ID&code=1234"
nexmo.verify.check({request_id: UNIQUE_ID_FROM_VERIFICATION_REQUEST, code: '1234'}, callback);
import com.nexmo.client.verify.CheckResult;

String requestId = request.getRequestId();
CheckResult result = client.check(requestId, CODE);
<?php
$client->verify()->check($verification, '1234');
response = client.check_verification(verify_resp['request_id'], code='1234')
if response['status'] == '0':
    print 'User verification complete!'
response = client.verify.check(request_id: REQUEST_ID, code: '1234')

puts "User verification complete!" if response.status == '0'

Cancel

If the user decides to cancel the verification process, you should send a cancellation request to Nexmo. This will prevent the verification process being completed even if the correct PIN is returned.

curl "https://api.nexmo.com/verify/control/json?api_key=API_KEY&api_secret=API_SECRET&request_id=REQUEST_ID&cmd=cancel"
<?php
$verification = new \Nexmo\Verify\Verification('00e6c3377e5348cdaf567e1417c707a5');
$client->verify()->cancel($verification);
client.cancel_verification(verify_resp['request_id'])
client.verify.cancel(REQUEST_ID)

Trigger next verification process

The Verify API starts the verification process by sending a text message to the user. If the PIN is not confirmed, Nexmo will attempt to contact the user via voice call.

You can make the API switch to the next verification process by sending an API call to the Verify Control endpoint. In the context of integrating the Verify API into your application, you should generally send this call to the API if the user has confirmed they would prefer to get a phone call.

curl "https://api.nexmo.com/verify/control/json?api_key=API_KEY&api_secret=API_SECRET&request_id=REQUEST_ID&cmd=trigger_next_event"
<?php
$verification = new \Nexmo\Verify\Verification('00e6c3377e5348cdaf567e1417c707a5');
$client->verify()->trigger($verification);
client.trigger_next_verification_event(verify_resp['request_id'])
client.verify.trigger_next_event(REQUEST_ID)