Verify API (v1)
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/overview
Operaciones disponibles
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
statusfield in the response to ensure that your request was successful (zero is success).Use the
request_idfield in the response for the Verify check.
Note that this endpoint is available by GET request as well as POST.
Autenticación
| Clave | Descripción | Dónde | Ejemplo |
|---|---|---|---|
| Authorization | Clave API codificada en Base64 y secreto unidos por dos puntos. | Headers | Basic <base64> |
447700900000The mobile or landline phone number to verify. Unless you are setting country explicitly, this number must be in E.164 format.
GBIf 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.
18Acme IncAn 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 ..."
11VERIFYACMEAn 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.
46The length of the verification code.
46en-usen-usBy 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/verify-v1/guides/verify-languages
ar-xacs-czcy-cycy-gbda-dkde-deel-gren-auen-gben-inen-uses-eses-mxes-usfi-fifil-phfr-cafr-frhi-inhu-huid-idis-isit-itja-jpko-krnb-nonl-nlpl-plpt-brpt-ptro-roru-rusv-seth-thtr-trvi-vnyue-cnzh-cnzh-tw603600300240How 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.
60900300120Specifies the wait time in seconds between attempts to deliver the verification code.
14Selects 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.
1234567410AKFG-3424A custom PIN to send to the user. If a PIN is not provided, Verify will generate a random PIN for you. This feature is not enabled by default - please discuss with your Account Manager if you would like it enabled. If this feature is not enabled on your account, error status 20 will be returned.
Ejemplo Solicitar
POST /verify/:format HTTP/1.1
Host: api.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 151
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&pin_code=AKFG-3424POST /verify/:format HTTP/1.1
Host: api.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 151
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&pin_code=AKFG-342432abcdef0123456789abcdef0123456789The unique ID of the Verify request. You need this request_id for the Verify check.
0Indicates the outcome of the request; zero is success
Ejemplo Respuesta»Success
{
"request_id": "abcdef0123456789abcdef0123456789",
"status": "0"
}PSD2 (Payment Services Directive 2) Request
Use Verify request to generate and send a PIN to your user to authorize a payment:
- Create a request to send a verification code to your user.
- Check the
statusfield in the response to ensure that your request was successful (zero is success). - Use the
request_idfield in the response for the Verify check. (Please note that XML format is not supported for the Payment Services Directive endpoint at this time.)
Autenticación
| Clave | Descripción | Dónde | Ejemplo |
|---|---|---|---|
| Authorization | Clave API codificada en Base64 y secreto unidos por dos puntos. | Headers | Basic <base64> |
447700900000The mobile or landline phone number to verify. Unless you are setting country explicitly, this number must be in E.164 format.
GBIf 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.
18Acme IncAn alphanumeric string to indicate to the user the name of the recipient that they are confirming a payment to.
48.00The decimal amount of the payment to be confirmed, in Euros
46The length of the verification code.
46en-gbes-esBy 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
en-gbbg-bgcs-czda-dkde-deee-etel-gres-esfi-fifr-frga-iehu-huit-itlv-lvlt-ltmt-mtnl-nlpl-plsk-sksl-sisv-se603600300240How 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.
60900300120Specifies the wait time in seconds between attempts to deliver the verification code.
14Selects 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.
1234567Ejemplo Solicitar
POST /verify/psd2/:format HTTP/1.1
Host: api.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 130
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=4POST /verify/psd2/:format HTTP/1.1
Host: api.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 130
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=432abcdef0123456789abcdef0123456789The unique ID of the Verify request. You need this request_id for the Verify check.
0Indicates the outcome of the request; zero is success
Ejemplo Respuesta»Success
{
"request_id": "abcdef0123456789abcdef0123456789",
"status": "0"
}Operaciones disponibles
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
codethat your user supplied, with the correspondingrequest_idfrom the Verify request. - Check the
statusof 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.
Autenticación
| Clave | Descripción | Dónde | Ejemplo |
|---|---|---|---|
| Authorization | Clave API codificada en Base64 y secreto unidos por dos puntos. | Headers | Basic <base64> |
32abcdef0123456789abcdef0123456789The Verify request to check. This is the request_id you received in the response to the Verify request.
461234The verification code entered by your user.
123.0.0.255(This field is no longer used)
Ejemplo Solicitar
POST /verify/check/:format HTTP/1.1
Host: api.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 76
request_id=abcdef0123456789abcdef0123456789&code=1234&ip_address=123.0.0.255POST /verify/check/:format HTTP/1.1
Host: api.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 76
request_id=abcdef0123456789abcdef0123456789&code=1234&ip_address=123.0.0.255abcdef0123456789abcdef0123456789The request_id that you received in the response to the Verify request and used in the Verify check request.
0A00000012345678The ID of the verification event, such as an SMS or TTS call.
0A value of 0 indicates that your user entered the correct code. If it is non-zero, check the error_text.
0.10000000The cost incurred for this request.
EURThe currency code.
0.03330000This 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.
Ejemplo Respuesta»Success
{
"request_id": "abcdef0123456789abcdef0123456789",
"event_id": "0A00000012345678",
"status": "0",
"price": "0.10000000",
"currency": "EUR",
"estimated_price_messages_sent": "0.03330000"
}Operaciones disponibles
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
statusof each verification request in thechecksarray of the response object to determine the outcome.
Note that this endpoint is available by POST request as well as GET.
Autenticación
| Clave | Descripción | Dónde | Ejemplo |
|---|---|---|---|
| Authorization | Clave API codificada en Base64 y secreto unidos por dos puntos. | Headers | Basic <base64> |
abcdef0123456789abcdef0123456789The request_id that you received in the response to the Verify request and used in the Verify search request.
abcdef01The Vonage account ID the request was for.
IN PROGRESS| 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. |
IN PROGRESSSUCCESSFAILEDEXPIREDCANCELLED447700900000The phone number this verification request was used for.
0.10000000The cost incurred for this verification request.
EURThe currency code.
verifymySenderIdThe sender_id you provided in the Verify request.
2020-01-01 12:00:00The date and time the verification request was submitted, in the following format YYYY-MM-DD HH:MM:SS.
2020-01-01 12:00:00The date and time the verification request was completed. This response parameter is in the following format YYYY-MM-DD HH:MM:SS.
2020-01-01 12:00:00The time the first verification attempt was made, in the following format YYYY-MM-DD HH:MM:SS.
2020-01-01 12:00:00The time the last verification attempt was made, in the following format YYYY-MM-DD HH:MM:SS.
The list of checks made for this verification and their outcomes.
2020-01-01 12:00:00The date and time this check was received (in the format YYYY-MM-DD HH:MM:SS)
987654The code supplied with this check request
VALIDINVALID123.0.0.255The IP address, if available (this field is no longer used).
The events that have taken place to verify this number, and their unique identifiers.
ttssms0.03330000This 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.
Ejemplo Respuesta»Success
{
"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": "VALID",
"ip_address": "123.0.0.255"
}
],
"events": [
{
"type": "tts",
"id": "string"
}
],
"estimated_price_messages_sent": "0.03330000"
}Operaciones disponibles
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
statusin the response.
Note that this endpoint is available by GET request as well as POST.
Autenticación
| Clave | Descripción | Dónde | Ejemplo |
|---|---|---|---|
| Authorization | Clave API codificada en Base64 y secreto unidos por dos puntos. | Headers | Basic <base64> |
abcdef0123456789abcdef0123456789The request_id you received in the response to the Verify request.
cancelThe 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.
canceltrigger_next_eventEjemplo Solicitar
POST /verify/control/:format HTTP/1.1
Host: api.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 54
request_id=abcdef0123456789abcdef0123456789&cmd=cancelPOST /verify/control/:format HTTP/1.1
Host: api.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 54
request_id=abcdef0123456789abcdef0123456789&cmd=cancelOperaciones disponibles
Autenticación
| Clave | Descripción | Dónde | Ejemplo |
|---|---|---|---|
| Authorization | Clave API codificada en Base64 y secreto unidos por dos puntos. | Headers | Basic <base64> |
32526The Network code
8640036003600An optional duration the unblock will be applied for in seconds
Ejemplo Solicitar
{
"network": 32526,
"unblock_duration": "3600"
}{
"network": 32526,
"unblock_duration": "3600"
}