Welcome to Nexmo Developer

We are improving our Documentation, API references, learning resources & tooling to help you more effectively use our services. We want to help you find everything you need to integrate Nexmo APIs into your code.

As we start this transition, we’d love to hear from you with thoughts & suggestions. If you’ve got something, positive or negative, to tell us, please tell us using the feedback tool at the bottom of each guide or file an issue on GitHub. - Nexmo

Verify API Reference

You use Verify API to Verify that a phone number is valid, reachable, and accessible by your user. You can customise the message used during verification.

The endpoints for Verify API are:

Verify Request

To use Verify Request you:

  • Create a Request to send a PIN to your user.
  • Check the response codes in the Response to ensure that your request was successful.

Request

GET  https://api.nexmo.com/verify/:format

Parameters

The following table shows the parameters you use in the request:

Parameter Description Required
format The response format. Either json or xml Yes
number The mobile or landline phone number to verify. Unless you are setting country explicitly, this number must be in E.164  format. For example, 447700900000. Yes
country If do not set number in international format or you are not sure if number is correctly formatted, set country with the two-character country code. For example, GB, US. Verify works out the international phone number for you. No
brand The name of the company or App you are using Verify for. This 18 character alphanumeric string is used in the body of Verify message. For example: "Your brand PIN is ..". Yes
sender_id An 11 character alphanumeric string to specify the SenderID for SMS sent by Verify. Depending on the destination of the phone number you are applying, restrictions may apply. By default, sender_id is VERIFY. No
code_length The length of the PIN. Possible values are 6 or 4 characters. The default value is 4. No
lg By default, the SMS or text-to-speech (TTS) message is generated in the locale that matches the number. For example, the text message or TTS message for a 33* number is sent in French. Use this parameter to explicitly control the language, accent and gender used for the Verify request. The default language is en-us. No
require_type Restrict verification to a certain network type. Possible values are:
  • All (Default)
  • Mobile
  • Landline

Note: contact support@nexmo.com to enable this feature.
No
pin_expiry The PIN validity time from generation. This is an integer value between 60 and 3600 seconds. The default is 300 seconds. When specified together, pin_expiry must be an integer multiple of next_event_wait. Otherwise, pin_expiry is set to equal next_event_wait. For example:
  • pin_expiry = 360 seconds, so next_event_wait = 120 seconds - all three attempts have the same PIN.
  • pin_expiry = 240 seconds, so next_event_wait = 120 seconds - 1st and 2nd attempts have the same PIN, third attempt has a different PIN.
  • pin_expiry = 120 (or 200 or 400 seconds) - each attempt has a different PIN.
No
next_event_wait An integer value between 60 and 900 seconds inclusive that specifies the wait time between attempts to deliver the PIN. Verify calculates the default value based on the average time taken by users to complete verification. No

Response

The following table shows example Responses in JSON or XML:

JSON

{
  "request_id":"requestId",
  "status":"status",
  "error_text":"error"
}

or XML

<?xml version='1.0' encoding='UTF-8' ?>
<verify_response>
    <request_id>requestId</request_id>
    <status>status</status>
    <error_text>error</error_text>
</verify_response>

Keys and Values

The response contains the following keys and values:

Key Value
request_id The unique ID of the Verify request you sent. The value of request_id is up to 32 characters long. You use this request_id for the Verify Check.
status The response code that explains how your request proceeded. (verify_response_codes: somevalue)
error_text If status is not 0, this explains the error encountered.

Status values

Status code Text Description
0 Success The request was successfully accepted by Nexmo.
1 Throttled You are trying to send more than the maximum of 30 requests per second.
2 Your request is incomplete and missing the mandatory parameter: $parameter The stated parameter is missing.
3 Invalid value for parameter: $parameter Invalid value for parameter. If you see Facility not allowed in the error text, check that you are using the correct Base URL in your request.
4 Invalid credentials were provided The supplied API key or secret in the request is either invalid or disabled.
5 Internal Error An error occurred processing this request in the Cloud Communications Platform.
6 The Nexmo platform was unable to process this message for the following reason: $reason The request could not be routed.
7 The number you are trying to verify is blacklisted for verification
8 The api_key you supplied is for an account that has been barred from submitting messages
9 Partner quota exceeded Your account does not have sufficient credit to process this request.
10 Concurrent verifications to the same number are not allowed
15 The destination number is not in a supported network The request has been rejected.
16 The code inserted does not match the expected value
17 The wrong code was provided too many times You can run Verify Check on a request_id up to three times unless a new PIN code is generated. If you check a request more than 3 times, it is set to FAILED and you cannot check it again.
18 Too many request_ids provided You added more than the maximum of 10 request_ids to your request.
19 No more events are left to execute for the request
101 No request found There are no matching Verify requests.

Verify Check

To use Verify Check you:

  • Use a check request to send the PIN you received from your user to Nexmo.
  • Check the response codes in the response to see if the PIN sent by your user matched the PIN generated by Nexmo.

Request

GET  https://api.nexmo.com/verify/check/:format

Parameters

The following table shows the parameters you use in the request:

Parameter Description Required
format The response format. Either json or xml. Yes
request_id The identifier of the Verify request to check. This is the request_id you received in the Verify Request response. Yes
code The PIN given by your user. Yes
ip_address The IP Address used by your user when they entered the PIN. Nexmo uses this information to identify fraud and spam patterns across our customer base. This ultimately benefits all Nexmo customers. No

Response

The following table shows example responses in JSON or XML:

JSON

{
  "request_id": "aaaaaaaafffffffff0000000099999999",
  "status": "0",
  "event_id": "aaaaaaaafffffffff0000000099999999",
  "price": "0.10000000",
  "currency": "EUR"
}

or XML

<?xml version='1.0' encoding='UTF-8' ?>
<verify_response>
  <event_id>requestId</event_id>
  <status>status</status>
  <price>price</price>
  <currency> currency</currency>
  <error_text>error</error_text>
</verify_response>

Keys and Values

The response contains the following keys and values:

Key Value
event_id The identifier of the SMS message-id.
status If the value of status is 0, your user entered the correct PIN. If it is not, check the response code.
price The price charged for this Verify request.
currency Currency code.
error_text If status is not 0, this is brief explanation about the error.
  1. Send a Verify Search request containing the request_id's of the Verify requests to search for.
  2. Check the status response parameter in the Search Response to see if the request was successfully completed.

Request

GET  https://api.nexmo.com/verify/search/:format

Parameters

The following table shows the parameters you use in the request:

Parameter Description Required
format The response format. Either json or xml Yes
request_id The request_id you received in the Verify Request Response. Conditional
request_ids More than one request_id. Each request_id is a new parameter in the Verify Search request. Conditional

Response

The following table shows example responses in JSON or XML:

JSON

{
   "request_id":"requestId",
   "account_id":"accountId",
   "number":"number",
   "sender_id":"sender",
   "date_submitted":"date",
   "date_finalized":"date",
   "first_event_date":"date",
   "last_event_date":"date",
   "status":"status",
   "price":"price",
   "currency":"currency",
   "error_text":"error",
   "checks":[
      {
         "date_received":"date",
         "code":"code",
         "status":"status",
         "ip_address":"ip"
      }
   ]
}

or XML

<?xml version='1.0' encoding='UTF-8' ?>
<verify_request>
    <request_id>requestId</request_id>
    <account_id>accountId</account_id>
    <number>number</number>
    <sender_id>senderId</sender_id>
    <date_submitted>date</date_submitted>
    <date_finalized>date</date_finalized>
    <checks>
       <check>
       <date_received>date</date_received>
       <status> status</status>
       <code>code</code>
       </check>
    </checks>
    <price>price</price>
    <currency> currency</currency>
    <error_text>error</error_text>
    <status>status</status>
</verify_request>

Keys and Values

The response contains the following keys and values:

Key Value
request_id The request_id you received in the Verify Request Response and used in the Verify Search request.
account_id The Account ID the request was for.
status The status of the Verify Request. Possible values are:
  • IN PROGRESS - still in progress.
  • SUCCESS - your user entered the PIN correctly.
  • FAILED - user entered the wrong pin more than 3 times.
  • EXPIRED - no PIN entered during the pin_expiry time.
  • CANCELLED - the request was cancelled using Verify Control
  • 101 - the request_id you set in the Verify Search request is invalid.
    number The phone number this Verify Request was made for.
    price The price charged for this Verify Request.
    currency The currency code.
    sender_id The sender_id you provided in the Verify Request.
    date_submitted The date and time the Verification Request was submitted. This response parameter is in the following format YYYY-MM-DD HH:MM:SS. For example, 2012-04-05 09:22:57.
    date_finalized The date and time the Verification Request was completed. This response parameter is in the following format YYYY-MM-DD HH:MM:SS. For example, 2012-04-05 09:22:57.
    first_event_date Time first attempt was made. This response parameter is in the following format YYYY-MM-DD HH:MM:SS. For example, 2012-04-05 09:22:57.
    last_event_date Time last attempt was made. This response parameter is in the following format YYYY-MM-DD HH:MM:SS. For example, 2012-04-05 09:22:57.
    checks The list of checks made for this verification and their outcomes. Possible values are:
    • date_received - in YYYY-MM-DD HH:MM:SS format
    • code
    • status - possible values are:
      • VALID
      • INVALID
    • ip_address
    error_text If status is not SUCCESS, this message explains the issue.

    Verify Control

    To control the progress of your Verify Requests:

    1. Send a Verify request.
    2. Check the response.

    Request

    GET  https://api.nexmo.com/verify/control/:format
    

    Parameters

    The following table shows the parameters you use in the request:

    Parameter Description Required
    format The response format. Either json or xml Yes
    request_id The request_id you received in the Verify Request Response. Yes
    cmd Change the command workflow. Supported values are:
    • cancel - stop the request
    • trigger_next_event - advance the request to the next part of the process.
    Verification requests can't be cancelled within the first 30 seconds. You must wait at least 30s after sending a Verify Request before cancelling.
    Yes

    Response

    Example responses in JSON and XML:

    JSON

    {
      "status":"0",
      "command":"cancel"
    }
    

    or XML

    <?xml version='1.0' encoding='UTF-8' ?>
    <response>
        <status>0</status>
        <command>cancel</command>
    </response>
    

    Keys and Values

    The response contains the following keys and values:

    Key Value
    status The Verify Control Response code that explains how your request proceeded. Possible Values.
    command The cmd you sent in the request.

    Language codes

    The following languages are accepted on the Verify API. The language code is used to manually set the language of the SMS text messgae and both the language, accent and voice gender for the subsequent phone call.

    Code Language Available genders
    de-de German, German female / male
    en-au English, Australian female / male
    en-gb English, UK female / male
    en-us English, US (default) female / male
    en-in English, Indian female
    es-es Spanish, Spanish female / male
    es-mx Spanish, Mexican female
    es-us Spanish, US female / male
    fr-ca French, Canadian female
    fr-fr French, French female / male
    is-is Icelandic, Icelandic female / male
    it-it Italian, Italian female / male
    ja-jp Japanese, Japanese female / male
    ko-kr Korean, Korean female / male
    nl-nl Dutch, Netherlands female / male
    pl-pl Polish, Polish female / male
    pt-pt Portuguese, Portuguese male
    pt-br Portuguese, Brazilian female / male
    ro-ro Romanian, Romanian female
    ru-ru Russian, Russian female
    sv-se Swedish, Sweden female
    tr-tr Turkish, Turkish female
    zh-cn Chinese (Mandarin), Simplified Chinese female / male
    zh-tw Chinese, Traditional text only - see note below

    If you request Taiwanese (zh-tw), the text message will be sent in Traditional Chinese, but the voice call uses a female voice speaking English with a Chinese accent.

    Code Command Error Text Meaning
    0 Success Success. Success.
    19 Cancel Verification requests can't be cancelled within the first 30 seconds. You must wait at least 30s after sending a Verify Request before cancelling.
    19 Cancel Verification requests can't be cancelled now. Too many attempts to re-deliver have already been made. Verify has made too many attempts to redeliver a PIN for this request; you have to wait for the workflow to complete. Also, you cannot initiate a new Verify Request until this one expires.
    19 Trigger_Next_Event No more events are left to execute All the attempts to deliver the PIN for this request have been completed and there are no more events to skip to.