Verify API

The Verify API helps you to implement 2FA (two-factor authentication) in your applications. This is useful for:

Protecting against spam, by preventing spammers from creating multiple accounts
Monitoring suspicious activity, by forcing an account user to verify ownership of a number
Ensuring that you can reach your users at any time because you have their correct phone number More information is available at https://developer.nexmo.com/verify

There are multiple versions of this API available

Verify Check

Use Verify check to confirm that the PIN you received from your user matches the one sent by Vonage in your Verify request.

Send the verification code that your user supplied, with the corresponding request_id from the Verify request.
Check the status of the response to determine if the code the user supplied matches the one sent by Vonage.

Note that this endpoint is available by GET request as well as POST.

POST


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

Host


        https://api.nexmo.com

POST


        /verify/check/:format

Path Parameters

format

string | Required

The response format.

Must be one of: json or xml

Request body application/x-www-form-urlencoded

api_key

string | Required

You can find your API key in your account dashboard

api_secret

string | Required

You can find your API secret in your account dashboard

request_id

string | Required | Max: 32

The Verify request to check. This is the request_id you received in the response to the Verify request.

code

string | Required | Min: 4 | Max: 6

The verification code entered by your user.

ip_address

string | DEPRECATED : This field has been deprecated.

(This field is no longer used)

Responses

200 OK

request_id

string

The request_id that you received in the response to the Verify request and used in the Verify check request.

event_id

string

The ID of the verification event, such as an SMS or TTS call.

status

string

A value of 0 indicates that your user entered the correct code. If it is non-zero, check the error_text.

price

string

The cost incurred for this request.

currency

string

The currency code.

estimated_price_messages_sent

string

This field may not be present, depending on your pricing model. The value indicates the cost (in EUR) of the calls made and messages sent for the verification process. This value may be updated during and shortly after the request completes because user input events can overlap with message/call events. When this field is present, the total cost of the verification is the sum of this field and the price field.

request_id

string

The request_id that you received in the response to the Verify request and used in the Verify check request.

status

string

Code	Text	Description
0	Success	The request was successfully accepted by Vonage.
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 Vonage platform was unable to process this message for the following reason: `$reason`	The request could not be routed.
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 specific `request_id` up to three times unless a new verification code is generated. If you check a request more than three times, it is set to FAILED and you cannot check it again.

One of: 0, 1, 2, 3, 4, 5, 6, 16 or 17

error_text

string

If the status is non-zero, this explains the error encountered.

request_id

string

The request_id that you received in the response to the Verify request and used in the Verify check request.

event_id

string

The ID of the verification event, such as an SMS or TTS call.

status

string

A value of 0 indicates that your user entered the correct code. If it is non-zero, check the error_text.

price

string

The cost incurred for this request.

currency

string

The currency code.

estimated_price_messages_sent

string

request_id

string

The request_id that you received in the response to the Verify request and used in the Verify check request.

status

string

Code	Text	Description
0	Success	The request was successfully accepted by Vonage.
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 Vonage platform was unable to process this message for the following reason: `$reason`	The request could not be routed.
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 specific `request_id` up to three times unless a new verification code is generated. If you check a request more than three times, it is set to FAILED and you cannot check it again.

One of: 0, 1, 2, 3, 4, 5, 6, 16 or 17

error_text

string

If the status is non-zero, this explains the error encountered.

Example Request

POST /verify/check/:format HTTP/1.1
Host: api.nexmo.com 
Content-Type: application/x-www-form-urlencoded
Content-Length: 99

api_key=abcd1234&api_secret=Sup3rS3cr3t%21%21&request_id=abcdef0123456789abcdef0123456789&code=1234

POST /verify/check/:format HTTP/1.1
Host: api.nexmo.com 
Content-Type: application/x-www-form-urlencoded
Content-Length: 122

api_key=abcd1234&api_secret=Sup3rS3cr3t%21%21&request_id=abcdef0123456789abcdef0123456789&code=1234&ip_address=123.0.0.255

Example Responses

200

{
  "request_id": "abcdef0123456789abcdef0123456789",
  "event_id": "0A00000012345678",
  "status": "0",
  "price": "0.10000000",
  "currency": "EUR",
  "estimated_price_messages_sent": "0.03330000"
}

{
  "request_id": "abcdef0123456789abcdef0123456789",
  "status": "16",
  "error_text": "The code inserted does not match the expected value"
}

<?xml version="1.0" encoding="UTF-8"?>
<verify_response>
  <request_id>abcdef0123456789abcdef0123456789</request_id>
  <event_id>0A00000012345678</event_id>
  <status>0</status>
  <price>0.10000000</price>
  <currency>EUR</currency>
  <estimated_price_messages_sent>0.03330000</estimated_price_messages_sent>
</verify_response>

<?xml version="1.0" encoding="UTF-8"?>
<verify_response>
  <request_id>abcdef0123456789abcdef0123456789</request_id>
  <status>16</status>
  <error_text>
    The code inserted does not match the expected value
  </error_text>
</verify_response>

Verify Search

Use Verify search to check the status of past or current verification requests:

Send a Verify search request containing the request_ids of the verification requests you are interested in.
Use the status of each verification request in the checks array of the response object to determine the outcome.

Note that this endpoint is available by POST request as well as GET.

GET


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

Host


        https://api.nexmo.com

GET


        /verify/search/:format

Path Parameters

format

string | Required

The response format.

Must be one of: json or xml

Query Parameter

api_key

string | Required

You can find your API key in your account dashboard

api_secret

string | Required

You can find your API secret in your account dashboard

request_id

string | Required

The request_id you received in the Verify Request Response. Required if request_ids not provided.

request_ids

array of strings

More than one request_id. Each request_id is a new parameter in the Verify Search request. Required if request_id not provided.

Responses

200 OK

request_id

string

The request_id that you received in the response to the Verify request and used in the Verify search request.

account_id

string

The Vonage account ID the request was for.

status

string

Code	Description
IN PROGRESS	The search is still in progress.
SUCCESS	Your user entered a correct verification code.
FAILED	Your user entered an incorrect code more than three times.
EXPIRED	Your user did not enter a code before the `pin_expiry` time elapsed.
CANCELLED	The verification process was cancelled by a Verify control request.

One of: IN PROGRESS, SUCCESS, FAILED, EXPIRED or CANCELLED

number

string

The phone number this verification request was used for.

price

string

The cost incurred for this verification request.

currency

string

The currency code.

sender_id

string

The sender_id you provided in the Verify request.

date_submitted

string

The date and time the verification request was submitted, in the following format YYYY-MM-DD HH:MM:SS.

date_finalized

string

The date and time the verification request was completed. This response parameter is in the following format YYYY-MM-DD HH:MM:SS.

first_event_date

string

The time the first verification attempt was made, in the following format YYYY-MM-DD HH:MM:SS.

last_event_date

string

The time the last verification attempt was made, in the following format YYYY-MM-DD HH:MM:SS.

checks

array of objects

The list of checks made for this verification and their outcomes.

string

The date and time this check was received (in the format YYYY-MM-DD HH:MM:SS)

string

The code supplied with this check request

string

One of: VALID or INVALID

string

The IP address, if available (this field is no longer used).

events

array of objects

The events that have taken place to verify this number, and their unique identifiers.

string

One of: tts or sms

string

estimated_price_messages_sent

string

request_id

string

The request_id that you received in the response to the Verify request and used in the Verify search request. May be empty in an error situation.

status

string

Code	Description
IN PROGRESS	The search is still in progress.
SUCCESS	Your user entered a correct verification code.
FAILED	Your user entered an incorrect code more than three times.
EXPIRED	Your user did not enter a code before the `pin_expiry` time elapsed.
CANCELLED	The verification process was cancelled by a Verify control request.
101	You supplied an invalid `request_id`, or the data is not available. Note that for recently-completed requests, there can be a delay of up to 1 minute before the results are available in search.

One of: IN PROGRESS, FAILED, EXPIRED, CANCELLED or 101

error_text

string

If status is not SUCCESS, this message explains the issue encountered.

request_id

string

The request_id that you received in the response to the Verify request and used in the Verify search request.

account_id

string

The Vonage account ID the request was for.

status

string

Code	Description
IN PROGRESS	The search is still in progress.
SUCCESS	Your user entered a correct verification code.
FAILED	Your user entered an incorrect code more than three times.
EXPIRED	Your user did not enter a code before the `pin_expiry` time elapsed.
CANCELLED	The verification process was cancelled by a Verify control request.

One of: IN PROGRESS, SUCCESS, FAILED, EXPIRED or CANCELLED

number

string

The phone number this verification request was used for.

price

string

The cost incurred for this verification request.

currency

string

The currency code.

sender_id

string

The sender_id you provided in the Verify request.

date_submitted

string

The date and time the verification request was submitted, in the following format YYYY-MM-DD HH:MM:SS.

date_finalized

string

The date and time the verification request was completed. This response parameter is in the following format YYYY-MM-DD HH:MM:SS.

first_event_date

string

The time the first verification attempt was made, in the following format YYYY-MM-DD HH:MM:SS.

last_event_date

string

The time the last verification attempt was made, in the following format YYYY-MM-DD HH:MM:SS.

checks

array of objects

The list of checks made for this verification and their outcomes.

string

The date and time this check was received (in the format YYYY-MM-DD HH:MM:SS)

string

The code supplied with this check request

string

One of: VALID or INVALID

string

The IP address, if available (this field is no longer used).

events

array of objects

The events that have taken place to verify this number, and their unique identifiers.

string

One of: tts or sms

string

estimated_price_messages_sent

string

request_id

string

The request_id that you received in the response to the Verify request and used in the Verify search request. May be empty in an error situation.

status

string

Code	Description
IN PROGRESS	The search is still in progress.
SUCCESS	Your user entered a correct verification code.
FAILED	Your user entered an incorrect code more than three times.
EXPIRED	Your user did not enter a code before the `pin_expiry` time elapsed.
CANCELLED	The verification process was cancelled by a Verify control request.
101	You supplied an invalid `request_id`, or the data is not available. Note that for recently-completed requests, there can be a delay of up to 1 minute before the results are available in search.

One of: IN PROGRESS, FAILED, EXPIRED, CANCELLED or 101

error_text

string

If status is not SUCCESS, this message explains the issue encountered.

Example Responses

200

{
  "request_id": "abcdef0123456789abcdef0123456789",
  "account_id": "abcdef01",
  "status": "IN PROGRESS",
  "number": "447700900000",
  "price": "0.10000000",
  "currency": "EUR",
  "sender_id": "mySenderId",
  "date_submitted": "2020-01-01 12:00:00",
  "date_finalized": "2020-01-01 12:00:00",
  "first_event_date": "2020-01-01 12:00:00",
  "last_event_date": "2020-01-01 12:00:00",
  "checks": [
    {
      "date_received": "2020-01-01 12:00:00",
      "code": "987654",
      "status": "abc123",
      "ip_address": "123.0.0.255"
    }
  ],
  "events": [
    {
      "type": "abc123",
      "id": "abc123"
    }
  ],
  "estimated_price_messages_sent": "0.03330000"
}

{
  "request_id": "abcdef0123456789abcdef0123456789",
  "status": "IN PROGRESS",
  "error_text": "No response found"
}

<?xml version="1.0" encoding="UTF-8"?>
<verify_request>
  <request_id>abcdef0123456789abcdef0123456789</request_id>
  <account_id>abcdef01</account_id>
  <status>IN PROGRESS</status>
  <number>447700900000</number>
  <price>0.10000000</price>
  <currency>EUR</currency>
  <sender_id>mySenderId</sender_id>
  <date_submitted>2020-01-01 12:00:00</date_submitted>
  <date_finalized>2020-01-01 12:00:00</date_finalized>
  <first_event_date>2020-01-01 12:00:00</first_event_date>
  <last_event_date>2020-01-01 12:00:00</last_event_date>
  <checks>
    <check>
      <date_received>2020-01-01 12:00:00</date_received>
      <code>987654</code>
      <status>abc123</status>
      <ip_address>123.0.0.255</ip_address>
    </check>
  </checks>
  <events>
    <event>
      <type>abc123</type>
      <id>abc123</id>
    </event>
  </events>
  <estimated_price_messages_sent>0.03330000</estimated_price_messages_sent>
</verify_request>

<?xml version="1.0" encoding="UTF-8"?>
<verify_request>
  <request_id>abcdef0123456789abcdef0123456789</request_id>
  <status>IN PROGRESS</status>
  <error_text>No response found</error_text>
</verify_request>

Verify Control

Control the progress of your Verify requests. To cancel an existing Verify request, or to trigger the next verification event:

Send a Verify control request with the appropriate command (cmd) for what you want to achieve.
Check the status in the response.

Note that this endpoint is available by GET request as well as POST.

POST


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

Host


        https://api.nexmo.com

POST


        /verify/control/:format

Path Parameters

format

string | Required

The response format.

Must be one of: json or xml

Request body application/x-www-form-urlencoded

api_key

string | Required

You can find your API key in your account dashboard

api_secret

string | Required

You can find your API secret in your account dashboard

request_id

string | Required

The request_id you received in the response to the Verify request.

cmd

string | Required

The possible commands are cancel to request cancellation of the verification process, or trigger_next_event to advance to the next verification event (if any). Cancellation is only possible 30 seconds after the start of the verification request and before the second event (either TTS or SMS) has taken place.

Must be one of: cancel or trigger_next_event

Responses

200 OK

status

string

`cmd`	Code	Description
Any	0	Success

command

string

The cmd you sent in the request.

One of: cancel or trigger_next_event

status

string

Code	Text	Description
0	Success	The request was successfully accepted by Vonage.
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 Vonage platform was unable to process this message for the following reason: `$reason`	The request could not be routed.
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.
19	For `cancel`: Either you have not waited at least 30 secs after sending a Verify request before cancelling or Verify has made too many attempts to deliver the verification code for this request and you must now wait for the process to complete. For `trigger_next_event`: All attempts to deliver the verification code for this request have completed and there are no remaining events to advance to.

One of: 0, 1, 2, 3, 4, 5, 6, 8, 9 or 19

error_text

string

If the status is non-zero, this explains the error encountered.

status

string

`cmd`	Code	Description
Any	0	Success

command

string

The cmd you sent in the request.

One of: cancel or trigger_next_event

status

string

Code	Text	Description
0	Success	The request was successfully accepted by Vonage.
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 Vonage platform was unable to process this message for the following reason: `$reason`	The request could not be routed.
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.
19	For `cancel`: Either you have not waited at least 30 secs after sending a Verify request before cancelling or Verify has made too many attempts to deliver the verification code for this request and you must now wait for the process to complete. For `trigger_next_event`: All attempts to deliver the verification code for this request have completed and there are no remaining events to advance to.

One of: 0, 1, 2, 3, 4, 5, 6, 8, 9 or 19

error_text

string

If the status is non-zero, this explains the error encountered.

Example Request

POST /verify/control/:format HTTP/1.1
Host: api.nexmo.com 
Content-Type: application/x-www-form-urlencoded
Content-Length: 100

api_key=abcd1234&api_secret=Sup3rS3cr3t%21%21&request_id=abcdef0123456789abcdef0123456789&cmd=cancel

Example Responses

200

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

{
  "status": "6",
  "error_text": "The requestId 'abcdef0123456789abcdef' does not exist or its no longer active."
}

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

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>6</status>
  <error_text>
    The requestId 'abcdef0123456789abcdef' does not exist or its no longer active.
  </error_text>
</response>

PSD2 (Payment Services Directive 2) Request

Use Verify request to generate and send a PIN to your user to authorize a payment: 1. Create a request to send a verification code to your user. 2. Check the status field in the response to ensure that your request was successful (zero is success). 3. Use the request_id field in the response for the Verify check. (Please note that XML format is not supported for the Payment Services Directive endpoint at this time.)

POST


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

Host


        https://api.nexmo.com

POST


        /verify/psd2/:format

Path Parameters

format

string | Required

The response format.

Must be one of: json or xml

Request body application/x-www-form-urlencoded

api_key

string | Required

You can find your API key in your account dashboard

api_secret

string | Required

You can find your API secret in your account dashboard

number

string | Required

The mobile or landline phone number to verify. Unless you are setting country explicitly, this number must be in E.164 format.

country

string

If you do not provide number in international format or you are not sure if number is correctly formatted, specify the two-character country code in country. Verify will then format the number for you.

payee

string | Required | Max: 18

An alphanumeric string to indicate to the user the name of the recipient that they are confirming a payment to.

amount

number (float) | Required

The decimal amount of the payment to be confirmed, in Euros

code_length

integer | Default: 4

The length of the verification code.

Must be one of: 4 or 6

string | Default: en-gb

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 used. *Note: Voice calls in English for bg-bg, ee-et, ga-ie, lv-lv, lt-lt, mt-mt, sk-sk, sk-si

Must be one of: en-gb, bg-bg, cs-cz, da-dk, de-de, ee-et, el-gr, es-es, fi-fi, fr-fr, ga-ie, hu-hu, it-it, lv-lv, lt-lt, mt-mt, nl-nl, pl-pl, sk-sk, sl-si or sv-se

pin_expiry

integer | Min: 60 | Max: 3600 | Default: 300

How long the generated verification code is valid for, in seconds. When you specify both pin_expiry and next_event_wait then pin_expiry must be an integer multiple of next_event_wait otherwise pin_expiry is defaulted to equal next_event_wait. See changing the event timings.

next_event_wait

integer | Min: 60 | Max: 900 | Default: 300

Specifies the wait time in seconds between attempts to deliver the verification code.

workflow_id

integer | Default: 1

Selects the predefined sequence of SMS and TTS (Text To Speech) actions to use in order to convey the PIN to your user. For example, an id of 1 identifies the workflow SMS - TTS - TTS. For a list of all workflows and their associated ids, please visit the developer portal.

Must be one of: 1, 2, 3, 4, 5, 6 or 7

Responses

200 OK

request_id

string

The unique ID of the Verify request. You need this request_id for the Verify check.

status

string

Indicates the outcome of the request; zero is success

request_id

string

The unique ID of the Verify request. This may be blank in an error situation

status

string

Code	Text	Description
0	Success	The request was successfully accepted by Vonage.
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 Vonage 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. Find out more about this error in the Knowledge Base
20	This account does not support the parameter: pin_code.	Only certain accounts have the ability to set the `pin_code`. Please contact your account manager for more information.
29	Non-Permitted Destination	Your Vonage account is still in demo mode. While in demo mode you must add target numbers to the approved list for your account. Add funds to your account to remove this limitation.

One of: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 20 or 29

error_text

string

If status is non-zero, this explains the error encountered.

This endpoint does not support text/xml

Example Request

POST /verify/psd2/:format HTTP/1.1
Host: api.nexmo.com 
Content-Type: application/x-www-form-urlencoded
Content-Length: 93

api_key=abcd1234&api_secret=Sup3rS3cr3t%21%21&number=447700900000&payee=Acme+Inc&amount=48.00

POST /verify/psd2/:format HTTP/1.1
Host: api.nexmo.com 
Content-Type: application/x-www-form-urlencoded
Content-Length: 176

api_key=abcd1234&api_secret=Sup3rS3cr3t%21%21&number=447700900000&country=GB&payee=Acme+Inc&amount=48.00&code_length=6&lg=es-es&pin_expiry=240&next_event_wait=120&workflow_id=4

Example Responses

200

{
  "request_id": "abcdef0123456789abcdef0123456789",
  "status": "0"
}

{
  "request_id": "",
  "status": "2",
  "error_text": "Your request is incomplete and missing the mandatory parameter `number`"
}

This endpoint does not support text/xml

Requests

Verify Requests

Available Operations:

post Request a Verification

Request a Verification

Use Verify request to generate and send a PIN to your user:

Create a request to send a verification code to your user.
Check the status field in the response to ensure that your request was successful (zero is success).
Use the request_id field in the response for the Verify check.

Note that this endpoint is available by GET request as well as POST.

POST


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

Host


        https://api.nexmo.com

POST


        /verify/:format

Path Parameters

format

string | Required

The response format.

Must be one of: json or xml

Request body application/x-www-form-urlencoded

api_key

string | Required

You can find your API key in your account dashboard

api_secret

string | Required

You can find your API secret in your account dashboard

number

string | Required

The mobile or landline phone number to verify. Unless you are setting country explicitly, this number must be in E.164 format.

country

string

brand

string | Required | Max: 18

An 18-character alphanumeric string you can use to personalize the verification request SMS body, to help users identify your company or application name. For example: "Your Acme Inc PIN is ..."

sender_id

string | Max: 11 | Default: VERIFY

An 11-character alphanumeric string that represents the identity of the sender of the verification request. Depending on the destination of the phone number you are sending the verification SMS to, restrictions might apply.

code_length

integer | Default: 4

The length of the verification code.

Must be one of: 4 or 6

string | Default: en-us

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 used for the Verify request. A list of languages is available: https://developer.nexmo.com/verify/guides/verify-languages

Must be one of: ar-xa, cs-cz, cy-cy, cy-gb, da-dk, de-de, el-gr, en-au, en-gb, en-in, en-us, es-es, es-mx, es-us, fi-fi, fil-ph, fr-ca, fr-fr, hi-in, hu-hu, id-id, is-is, it-it, ja-jp, ko-kr, nb-no, nl-nl, pl-pl, pt-br, pt-pt, ro-ro, ru-ru, sv-se, th-th, tr-tr, vi-vn, yue-cn, zh-cn or zh-tw

pin_expiry

integer | Min: 60 | Max: 3600 | Default: 300

next_event_wait

integer | Min: 60 | Max: 900 | Default: 300

Specifies the wait time in seconds between attempts to deliver the verification code.

workflow_id

integer | Default: 1

Must be one of: 1, 2, 3, 4, 5, 6 or 7

Responses

200 OK

request_id

string

The unique ID of the Verify request. You need this request_id for the Verify check.

status

string

Indicates the outcome of the request; zero is success

request_id

string

The unique ID of the Verify request. This may be blank in an error situation

status

string

Code	Text	Description
0	Success	The request was successfully accepted by Vonage.
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 Vonage 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. Find out more about this error in the Knowledge Base
20	This account does not support the parameter: pin_code.	Only certain accounts have the ability to set the `pin_code`. Please contact your account manager for more information.
29	Non-Permitted Destination	Your Vonage account is still in demo mode. While in demo mode you must add target numbers to the approved list for your account. Add funds to your account to remove this limitation.

One of: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 20 or 29

error_text

string

If status is non-zero, this explains the error encountered.

request_id

string

The unique ID of the Verify request. You need this request_id for the Verify check.

status

string

Indicates the outcome of the request; zero is success

request_id

string

The unique ID of the Verify request. This may be blank in an error situation

status

string

Code	Text	Description
0	Success	The request was successfully accepted by Vonage.
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 Vonage 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. Find out more about this error in the Knowledge Base
20	This account does not support the parameter: pin_code.	Only certain accounts have the ability to set the `pin_code`. Please contact your account manager for more information.
29	Non-Permitted Destination	Your Vonage account is still in demo mode. While in demo mode you must add target numbers to the approved list for your account. Add funds to your account to remove this limitation.

One of: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 20 or 29

error_text

string

If status is non-zero, this explains the error encountered.

Example Request

POST /verify/:format HTTP/1.1
Host: api.nexmo.com 
Content-Type: application/x-www-form-urlencoded
Content-Length: 80

api_key=abcd1234&api_secret=Sup3rS3cr3t%21%21&number=447700900000&brand=Acme+Inc

POST /verify/:format HTTP/1.1
Host: api.nexmo.com 
Content-Type: application/x-www-form-urlencoded
Content-Length: 178

api_key=abcd1234&api_secret=Sup3rS3cr3t%21%21&number=447700900000&country=GB&brand=Acme+Inc&sender_id=ACME&code_length=6&lg=en-us&pin_expiry=240&next_event_wait=120&workflow_id=4

Example Responses

200

{
  "request_id": "abcdef0123456789abcdef0123456789",
  "status": "0"
}

{
  "request_id": "",
  "status": "2",
  "error_text": "Your request is incomplete and missing the mandatory parameter `number`"
}

<?xml version="1.0" encoding="UTF-8"?>
<verify_response>
  <request_id>abcdef0123456789abcdef0123456789</request_id>
  <status>0</status>
</verify_response>

<?xml version="1.0" encoding="UTF-8"?>
<verify_response>
  <request_id/>
  <status>2</status>
  <error_text>
    Your request is incomplete and missing the mandatory parameter `number`
  </error_text>
</verify_response>

Fraud Management

Available Operations:

post Request a network unblock

Request a network unblock

Request to unblock a network that has been blocked due to potential fraud detection

Network Unblock is switched off by default.

Please contact Sales to enable the Network Unblock API for your account.

POST


        https://api.nexmo.com/verify/network-unblock

Host


        https://api.nexmo.com

POST


        /verify/network-unblock

Request body application/json

network

string

The Network code

unblock_duration

integer

Duration the unblock will be applied in seconds

Responses

202 Accepted

network

string

The unique network ID

unblocked_until

string

Gives the DateTime when the unblock will expire.

This endpoint does not support text/xml

Example Request

{
  "network": 32526,
  "unblock_duration": "3600"
}

Example Responses

202 404 403 422 429

{
  "network": "23410",
  "unblocked_until": "2024-04-22T08:34:58Z"
}

This endpoint does not support text/xml

{
  "type": "https://developer.vonage.com/api-errors#bad-request",
  "title": "Not Found",
  "detail": "The network you provided does not have an active block.",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}

This endpoint does not support text/xml

{
  "type": "https://developer.vonage.com/api-errors#forbidden",
  "title": "Forbidden",
  "detail": "Your account does not have permission to perform this action.",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}

This endpoint does not support text/xml

{
  "type": "https://developer.vonage.com/api-errors#invalid-paramater",
  "title": "Network not found.",
  "detail": "Network is not in the request.",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf",
  "invalid_parameters": {
    "name": "network",
    "reason": "Network not found"
  }
}

{
  "type": "https://developer.vonage.com/api-errors#invalid-paramater",
  "title": "Invalid unblock_duration parameter",
  "detail": "Unblock duration is invalid.",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf",
  "invalid_parameters": {
    "name": "unblock_duration",
    "reason": "Must be an integer in minutes"
  }
}

This endpoint does not support text/xml

{
  "type": "https://developer.vonage.com/api-errors/verify#rate-limit",
  "title": "Rate Limit Hit",
  "detail": "Please wait, then retry your request",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}

This endpoint does not support text/xml

Verify API

Jump to:

There are multiple versions of this API available

Verify Check

Path Parameters

Request body application/x-www-form-urlencoded

Responses

Example Request

Example Responses

Verify Search

Path Parameters

Query Parameter

Responses

Example Responses

Verify Control

Path Parameters

Request body application/x-www-form-urlencoded

Responses

Example Request

Example Responses

PSD2 (Payment Services Directive 2) Request

Path Parameters

Request body application/x-www-form-urlencoded

Responses

Example Request

Example Responses

Requests

Available Operations:

Request a Verification

Path Parameters

Request body application/x-www-form-urlencoded

Responses

Example Request

Example Responses

Fraud Management

Available Operations:

Request a network unblock

Network Unblock is switched off by default.

Request body application/json

Responses

Example Request

Example Responses