Verify API (v1)

Version 1

Version 2

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

OpenAPI-Spezifikation herunterladen

Verify Requests

Verfügbare Operationen

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.

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

Pfad Parameter

format

string

Erforderlich

The response format.

Muss eines der folgenden sein:jsonxml

Anfrage Körper
Inhalt Typ
application/x-www-form-urlencoded

api_key

string

Erforderlich

Beispielabcd1234

You can find your API key in your account dashboard

api_secret

string

Erforderlich

BeispielSup3rS3cr3t!!

You can find your API secret in your account dashboard

number

string

Erforderlich

Beispiel447700900000

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

country

string

BeispielGB

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.

brand

string

Erforderlich

Max18

BeispielAcme Inc

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

Max11

StandardVERIFY

BeispielACME

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

Standard4

Beispiel6

The length of the verification code.

Muss eines der folgenden sein:46

string

Standarden-us

Beispielen-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/verify-v1/guides/verify-languages

Muss eines der folgenden sein: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-tw

pin_expiry

integer

Min60

Max3600

Standard300

Beispiel240

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

Min60

Max900

Standard300

Beispiel120

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

workflow_id

integer

Standard1

Beispiel4

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.

Muss eines der folgenden sein:1234567

pin_code

string

Min4

Max10

BeispielAKFG-3424

A 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.

Beispiel Anfrage

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

api_key=abcd1234&api_secret=Sup3rS3cr3t!!&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-3424

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

api_key=abcd1234&api_secret=Sup3rS3cr3t!!&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-3424

Antworten
Inhalt Typ
application/json

Einer der

request_id

string

Max32

Beispielabcdef0123456789abcdef0123456789

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

status

string

Beispiel0

Indicates the outcome of the request; zero is success

Beispiel Antwort»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 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. (Please note that XML format is not supported for the Payment Services Directive endpoint at this time.)

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

Pfad Parameter

format

string

Erforderlich

The response format.

Muss eines der folgenden sein:jsonxml

Anfrage Körper
Inhalt Typ
application/x-www-form-urlencoded

api_key

string

Erforderlich

Beispielabcd1234

You can find your API key in your account dashboard

api_secret

string

Erforderlich

BeispielSup3rS3cr3t!!

You can find your API secret in your account dashboard

number

string

Erforderlich

Beispiel447700900000

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

country

string

BeispielGB

payee

string

Erforderlich

Max18

BeispielAcme Inc

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

amount

number(float)

Erforderlich

Beispiel48.00

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

code_length

integer

Standard4

Beispiel6

The length of the verification code.

Muss eines der folgenden sein:46

string

Standarden-gb

Beispieles-es

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

Muss eines der folgenden sein:en-gbbg-bgcs-czda-dkde-deee-etel-gres-esfi-fifr-frga-iehu-huit-itlv-lvlt-ltmt-mtnl-nlpl-plsk-sksl-sisv-se

pin_expiry

integer

Min60

Max3600

Standard300

Beispiel240

next_event_wait

integer

Min60

Max900

Standard300

Beispiel120

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

workflow_id

integer

Standard1

Beispiel4

Muss eines der folgenden sein:1234567

Beispiel Anfrage

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

api_key=abcd1234&api_secret=Sup3rS3cr3t!!&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

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

api_key=abcd1234&api_secret=Sup3rS3cr3t!!&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

Antworten
Inhalt Typ
application/json

Einer der

request_id

string

Max32

Beispielabcdef0123456789abcdef0123456789

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

status

string

Beispiel0

Indicates the outcome of the request; zero is success

Beispiel Antwort»Success

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

Verify Check

Verfügbare Operationen

Verify Check

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.

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

Pfad Parameter

format

string

Erforderlich

The response format.

Muss eines der folgenden sein:jsonxml

Anfrage Körper
Inhalt Typ
application/x-www-form-urlencoded

api_key

string

Erforderlich

Beispielabcd1234

You can find your API key in your account dashboard

api_secret

string

Erforderlich

BeispielSup3rS3cr3t!!

You can find your API secret in your account dashboard

request_id

string

Erforderlich

Max32

Beispielabcdef0123456789abcdef0123456789

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

code

string

Erforderlich

Min4

Max6

Beispiel1234

The verification code entered by your user.

ip_address

string

Beispiel123.0.0.255

(This field is no longer used)

Beispiel Anfrage

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

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

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

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

Antworten
Inhalt Typ
application/json

Einer der

request_id

string

Beispielabcdef0123456789abcdef0123456789

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

event_id

string

Beispiel0A00000012345678

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

status

string

Beispiel0

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

price

string

Beispiel0.10000000

The cost incurred for this request.

currency

string

BeispielEUR

The currency code.

estimated_price_messages_sent

string

Beispiel0.03330000

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.

Beispiel Antwort»Success

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

Verify Search

Verfügbare Operationen

Verify Search

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.

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

Pfad Parameter

format

string

Erforderlich

The response format.

Muss eines der folgenden sein:jsonxml

Abfrage Parameter

api_key

string

Beispielabcd1234

api_secret

string

BeispielSup3rS3cr3t!!

request_id

string

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

request_ids

array

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

Antworten
Inhalt Typ
application/json

Einer der

request_id

string

Beispielabcdef0123456789abcdef0123456789

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

account_id

string

Beispielabcdef01

The Vonage account ID the request was for.

status

string

BeispielIN 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.

Muss eines der folgenden sein:IN PROGRESSSUCCESSFAILEDEXPIREDCANCELLED

number

string

Beispiel447700900000

The phone number this verification request was used for.

price

string

Beispiel0.10000000

The cost incurred for this verification request.

currency

string

BeispielEUR

The currency code.

sender_id

string

Standardverify

BeispielmySenderId

The sender_id you provided in the Verify request.

date_submitted

string

Beispiel2020-01-01 12:00:00

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

date_finalized

string

Beispiel2020-01-01 12:00:00

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

Beispiel2020-01-01 12:00:00

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

last_event_date

string

Beispiel2020-01-01 12:00:00

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

checks

array

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

date_received

string

Beispiel2020-01-01 12:00:00

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

code

string

Beispiel987654

The code supplied with this check request

status

string

Muss eines der folgenden sein:VALIDINVALID

ip_address

string

Beispiel123.0.0.255

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

events

array

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

type

string

Muss eines der folgenden sein:ttssms

string

estimated_price_messages_sent

string

Beispiel0.03330000

Beispiel Antwort»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"
}

Verify Control

Verfügbare Operationen

Verify Control

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.

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

Pfad Parameter

format

string

Erforderlich

The response format.

Muss eines der folgenden sein:jsonxml

Anfrage Körper
Inhalt Typ
application/x-www-form-urlencoded

api_key

string

Erforderlich

Beispielabcd1234

You can find your API key in your account dashboard

api_secret

string

Erforderlich

BeispielSup3rS3cr3t!!

You can find your API secret in your account dashboard

request_id

string

Erforderlich

Beispielabcdef0123456789abcdef0123456789

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

cmd

string

Erforderlich

Beispielcancel

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.

Muss eines der folgenden sein:canceltrigger_next_event

Beispiel Anfrage

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

api_key=abcd1234&api_secret=Sup3rS3cr3t!!&request_id=abcdef0123456789abcdef0123456789&cmd=cancel

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

api_key=abcd1234&api_secret=Sup3rS3cr3t!!&request_id=abcdef0123456789abcdef0123456789&cmd=cancel

Antworten
Inhalt Typ
application/json

Einer der

status

string

Beispiel0

`cmd`	Code	Description
Any	0	Success

command

string

Beispielcancel

The cmd you sent in the request.

Muss eines der folgenden sein:canceltrigger_next_event

Beispiel Antwort»Success

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

Fraud Management

Verfügbare Operationen

Request a network unblock

Request a network unblock

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

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

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

Anfrage Körper
Inhalt Typ
application/json

network

string

Beispiel32526

The Network code

unblock_duration

integer

Erforderlich

Max86400

Standard3600

Beispiel3600

An optional duration the unblock will be applied for in seconds

Beispiel Anfrage

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

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

Antworten
Inhalt Typ
application/json

Accepted

network

string

Beispiel23410

The unique network ID

unblocked_until

string

Beispiel2024-04-22T08:34:58Z

Gives the DateTime when the unblock will expire.

Beispiel Antwort

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

Verify API (v1)

Verify Requests

Verfügbare Operationen

Request a Verification

Pfad Parameter

Anfrage Körper Inhalt Typapplication/x-www-form-urlencoded

Beispiel Anfrage

Antworten Inhalt Typapplication/json

Beispiel Antwort»Success

PSD2 (Payment Services Directive 2) Request

Pfad Parameter

Anfrage Körper Inhalt Typapplication/x-www-form-urlencoded

Beispiel Anfrage

Antworten Inhalt Typapplication/json

Beispiel Antwort»Success

Verify Check

Verfügbare Operationen

Verify Check

Pfad Parameter

Anfrage Körper Inhalt Typapplication/x-www-form-urlencoded

Beispiel Anfrage

Antworten Inhalt Typapplication/json

Beispiel Antwort»Success

Verify Search

Verfügbare Operationen

Verify Search

Pfad Parameter

Abfrage Parameter

Antworten Inhalt Typapplication/json

Beispiel Antwort»Success

Verify Control

Verfügbare Operationen

Verify Control

Pfad Parameter

Anfrage Körper Inhalt Typapplication/x-www-form-urlencoded

Beispiel Anfrage

Antworten Inhalt Typapplication/json

Beispiel Antwort»Success

Fraud Management

Verfügbare Operationen

Request a network unblock

Anfrage Körper Inhalt Typapplication/json

Beispiel Anfrage

Antworten Inhalt Typapplication/json

Beispiel Antwort

Anfrage Körper
Inhalt Typ
application/x-www-form-urlencoded

Antworten
Inhalt Typ
application/json

Anfrage Körper
Inhalt Typ
application/x-www-form-urlencoded

Antworten
Inhalt Typ
application/json

Anfrage Körper
Inhalt Typ
application/x-www-form-urlencoded

Antworten
Inhalt Typ
application/json

Antworten
Inhalt Typ
application/json

Anfrage Körper
Inhalt Typ
application/x-www-form-urlencoded

Antworten
Inhalt Typ
application/json

Anfrage Körper
Inhalt Typ
application/json

Antworten
Inhalt Typ
application/json