API reference

You use Verify API to Verify that a phone number is valid, reachable, and accessible by your user. You can customize 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

A Verify API request looks like:

https://api.nexmo.com/verify/json?api_key=xxxxxxxx&api_secret=xxxxxxxx&number=xxxxxxxxxxxx&brand=MyApp

This request contains:

Base URL

All requests to the Verify API must contain:

  • https://api.nexmo.com/verify
  • A response object: json or xml

Your base URL becomes either:

JSON XML
https://api.nexmo.com/verify/json https://api.nexmo.com/verify/xml

Parameters

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

Parameter Description Required
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, 4478342080934. 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, TTS are generated in the locale that matches number. For example, the TTS 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 next_event_wait. For example:
  • pin_expiry= 360 seconds, next_event_wait=120 seconds - all three attempts have the same PIN.
  • pin_expiry=240 seconds, 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

Each request you make to the Verify API returns a:

  • Response - the status and cost of your request to Nexmo in JSON or XML format.

Note: you are only charged for correctly submitted requests.

The response is send in the api.txt file when you make a request from the browser.

Each response comes:

Format

You set the response type using the Base URL. The following table shows example Responses in JSON or XML:

JSON XML
{
"request_id":"requestId",
"status":"status",
"error_text":"error"
}
<?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.
Code Error Text Meaning
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 A 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 api_key or api_secret you supplied 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 As error text.
8 The api_key you supplied is for an account that has been barred from submitting messages As error text.
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 As error text.
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 As error text.
17 The wrong code was provided too many times You can run Verify Check on a Verify 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 As error text.
101 No response found There are no matching Verify request.
error_text If status is not 0, this explains the error encountered.

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

A Verify Check request looks like:

https://api.nexmo.com/verify/check/json?api_key=xxxxxxxx&api_secret=xxxxxxxx&request_id=xxxxxxxxxxxx&code=xxxx

This request contains:

Base URL

All requests to Verify Check must contain:

  • https://api.nexmo.com/verify/check
  • A response object: json or xml

Your base URL becomes either:

JSON XML
https://api.nexmo.com/verify/check/json https://api.nexmo.com/verify/check/verify/xml

Parameters

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

Parameter Description Required
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 he or she provided the PIN. Nexmo uses this information to identify fraud and spam patterns across our customer base. This ultimately benefits all Nexmo customers No

Response

Each Verify Check request you make to Verify returns a:

  • Response - the status and cost of your request to Nexmo in JSON or XML format.

Note: you are only charged for correctly submitted requests.

Each response comes:

Format

You set the response type using the Base URL. The following table shows example responses in JSON or XML:

JSON XML
{
    "event_id":"eventId",
    "status":"status",
    "price":"price",
    "currency":"currency",
    "error_text":"error"
}
<?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:

Keys and Values

The response contains the following keys and values:

Key Value
event_id The identifier of either the SMS message-id or TTS call-id used by Verify to send the PIN.
status If the value of status is *0*, your user entered the correct PIN. If it is not, check the response codes:
Code Error Text Meaning
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 A 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 api_key or api_secret you supplied 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 As error text.
8 The api_key you supplied is for an account that has been barred from submitting messages As error text.
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 As error text.
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 As error text.
17 The wrong code was provided too many times You can run Verify Check on a Verify 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 As error text.
101 No response found There are no matching Verify request.
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.

Verify Search

  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

A Verify Search request looks like:

https://api.nexmo.com/verify/search/json?api_key=xxxxxxxx&api_secret=xxxxxxxx&request_id=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

To search on multiple requests use request_ids. A Verify Search request is:

https://api.nexmo.com/verify/search/json?api_key=xxxxxxxx&api_secret=xxxxxxxx&&request_ids=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&request_ids=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&request_ids=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

This request contains:

Base URL

All requests to the Verify API must contain:

  • https://api.nexmo.com/verify/search
  • A response object: json or xml

Your base URL becomes either:

JSON XML
https://api.nexmo.com/verify/search/json https://api.nexmo.com/verify/search/xml

Parameters

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

Parameter Description Required
request_id The request_id you received in the Verify Request Response. No
request_ids More than one request_id. Each request_id is a new parameter in the Verify Search request. No

Response

Each request you make to Verify Search returns a:

  • Response - the status and cost of your request to Nexmo in JSON or XML format.

Note: you are only charged for correctly submitted requests.

Each response comes:

Format

You set the response type using the Base URL. The following table shows example responses in JSON or XML:

JSON XML
{
"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"
   }
   ]
}
<?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.
  • SUCCESSFUL - 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 entered 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 SUCCESSFUL, 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

    A Verify Control request looks like:

    https://api.nexmo.com/verify/control/json?api_key=xxxxxxxx&api_secret=xxxxxxxx&request_id=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&cmd=cancel

    This request contains:

    Base URL

    All requests to the Verify API must contain:

    • https://api.nexmo.com/verify/control
    • A response object: json or xml

    Your base URL becomes either:

    JSON XML
    https://api.nexmo.com/verify/control/json https://api.nexmo.com/control/verify

    Parameters

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

    Parameter Description Required
    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

    Each request you make to Verify Control returns a:

    • Response - the status and cost of your request to Nexmo in JSON or XML format.

    Note: you are only charged for correctly submitted requests.

    Each response comes:

    Format

    You set the response type using the Base URL. The following table shows example responses in JSON or XML:

    JSON XML
    {
      "status":"0",
      "command":"cancel"
    }
    
    <?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:
    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.
    command The cmd you sent in the request.

    Authentication information

    If you are not using applications, you use the following parameters for calls to Nexmo API:

    Parameter Description
    api_key Your Key. For example: api_key=n3xm0rocks
    api_secret Your Secret. For example: api_secret=12ab34cd

    You find your Key and Secret in Dashboard.

    If you are using signatures to verify your requests use:

    Parameter Description
    api_key Your Key. For example: api_key=n3xm0rocks
    sig The hash of the request parameters in alphabetical order, a timestamp and the signature secret. For example: sig=TwoMenWentToMowWentTOMowAMeadowT

    Security

    To ensure privacy, you must use HTTPS for all Nexmo API requests.

    Encoding

    You submit all requests with a POST or GET call using UTF-8 encoding and URL encoded values. The expected Content-Type for POST is application/x-www-form-urlencoded. For calls to a JSON endpoint, we also support:

    • application/json
    • application/jsonrequest
    • application/x-javascript
    • text/json
    • text/javascript
    • text/x-javascript
    • text/x-json when posting parameters as a JSON object.
    Previous   Next