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

POST
request to the /v2/verify endpoint. This API call initializes the verification workflow that tries to deliver the OTP via SMS, and if that fails, via voice call.

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

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

Header Value Required Description
Authorization Bearer $JWT Yes Authenticates the API request using JWT.
Content-Type application/json Yes Specifies that the request body is formatted as JSON.

Body Field Required Type Description
brand Yes String The name of your company or service, shown to the user in the verification message (TestVerify in this example)
code_length No Integer The number of digits in the OTP code. Defaults to 4 if not specified.
channel_timeout No Integer Time (in seconds) to wait before moving to the next step in the workflow.
workflow Yes Array Defines the sequence of channels to deliver the OTP (e.g., SMS, voice). You can learn more about workflows in our workflow guide.
workflow.channel Yes String The delivery channel to use (sms, voice, whatsapp).
workflow.to Yes String The phone number to send the OTP to, in E.164 format (e.g., +44111223344).

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

POST
request to the /v2/verify/{request_id} endpoint, replacing {request_id} with the ID you received in the previous call:

curl -X POST "https://api.nexmo.com/v2/verify/$VERIFY_REQUEST_ID" \
  -H "Authorization: Bearer $JWT"\
  -H 'Content-Type: application/json' \
  -d $'{
    "code": "'$VERIFY_CODE'"
  }'

Request Headers:

Header Value Required Description
Authorization Bearer $JWT Yes Authenticates the API request using JWT.
Content-Type application/json Yes Specifies that the request body is formatted as JSON.

Request body:

Body Field Required Type Description
code Yes String The verification code received by the end-user

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"
}