Available Operations Requests Webhooks
 
 

Vonage Verify API (v2)

Verify API provides a choice of routes for sending a code to a user. You can use this to confirm a user's contact information, as a second factor when authenticating users, or for step-up authentication.

Available Operations:

There are multiple versions of this API available

Version 1 | Version 2

Request a verification be sent to a user

Start verifying that we can reach this user given a set of contact details

POST https://api.nexmo.com/v2/verify
Host https://api.nexmo.com
POST /v2/verify

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key Description Example Default
Authorization Your JSON web token.
Read more about JWTs
Bearer <JWT> None
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Request body application/json

brand
string | Required

The brand that is sending the verification request.

workflow
array of objects | Required

Request a code be sent to a user

channel
string

The channel

Must be one of: sms
to
string | Min: 1 | Max: 50

The phone number to contact, in the E.164 format. Don't use a leading + or 00 when entering a phone number, start with the country code, for example, 447700900000.

locale
string | Default: en-us

Languages that are available to use

Must be one of: en-us, en-gb, es-es, es-mx, es-us, it-it, fr-fr, de-de, ru-ru, hi-in, pt-br, pt-pt or id-id
channel_timeout
integer | Min: 60 | Max: 900 | Default: 300

Specifies the wait time in seconds between attempts to delivery the verification code

client_ref
string

If the client_ref is set when the request is sent, it will be included in the callbacks

code_length
integer | Default: 4

Length of the code to send to the user

Must be one of: 4, 5, 6, 7, 8, 9 or 10
brand
string | Required

The brand that is sending the verification request.

workflow
array of objects | Required

Request a code be sent to a user

channel
string

The channel

Must be one of: whatsapp
to
string | Min: 1 | Max: 50

The phone number to contact, in the E.164 format. Don't use a leading + or 00 when entering a phone number, start with the country code, for example, 447700900000.

template
string
locale
string | Default: en-us

Languages that are available to use

Must be one of: en-us, en-gb, es-es, es-mx, es-us, it-it, fr-fr, de-de, ru-ru, hi-in, pt-br, pt-pt or id-id
channel_timeout
integer | Min: 60 | Max: 900 | Default: 300

Specifies the wait time in seconds between attempts to delivery the verification code

client_ref
string

If the client_ref is set when the request is sent, it will be included in the callbacks

code_length
integer | Default: 4

Length of the code to send to the user

Must be one of: 4, 5, 6, 7, 8, 9 or 10
brand
string | Required

The brand that is sending the verification request.

workflow
array of objects | Required

Request a code be sent to a user

channel
string

The channel

Must be one of: whatsapp_interactive
to
string | Min: 1 | Max: 50

The phone number to contact, in the E.164 format. Don't use a leading + or 00 when entering a phone number, start with the country code, for example, 447700900000.

template
string
locale
string | Default: en-us

Languages that are available to use

Must be one of: en-us, en-gb, es-es, es-mx, es-us, it-it, fr-fr, de-de, ru-ru, hi-in, pt-br, pt-pt or id-id
channel_timeout
integer | Min: 60 | Max: 900 | Default: 300

Specifies the wait time in seconds between attempts to delivery the verification code

client_ref
string

If the client_ref is set when the request is sent, it will be included in the callbacks

code_length
integer | Default: 4

Length of the code to send to the user

Must be one of: 4, 5, 6, 7, 8, 9 or 10
brand
string | Required

The brand that is sending the verification request.

workflow
array of objects | Required

Request a code be sent to a user

channel
string

The channel

Must be one of: voice
to
string | Min: 1 | Max: 50

The phone number to contact, in the E.164 format. Don't use a leading + or 00 when entering a phone number, start with the country code, for example, 447700900000.

locale
string | Default: en-us

Languages that are available to use

Must be one of: en-us, en-gb, es-es, es-mx, es-us, it-it, fr-fr, de-de, ru-ru, hi-in, pt-br, pt-pt or id-id
channel_timeout
integer | Min: 60 | Max: 900 | Default: 300

Specifies the wait time in seconds between attempts to delivery the verification code

client_ref
string

If the client_ref is set when the request is sent, it will be included in the callbacks

code_length
integer | Default: 4

Length of the code to send to the user

Must be one of: 4, 5, 6, 7, 8, 9 or 10

Responses

202 The request was started
request_id
string

The ID of the request

Example Request » SMS

{
  "brand": "ACME, Inc",
  "workflow": [
    {
      "channel": "sms",
      "to": "447700900000"
    }
  ]
}
{
  "brand": "ACME, Inc",
  "workflow": [
    {
      "channel": "sms",
      "to": "447700900000"
    }
  ],
  "locale": "es-es",
  "channel_timeout": 300,
  "client_ref": "my-personal-reference",
  "code_length": 4
}

Example Request » WhatsApp

{
  "brand": "ACME, Inc",
  "workflow": [
    {
      "channel": "whatsapp",
      "to": "447700900000"
    }
  ]
}
{
  "brand": "ACME, Inc",
  "workflow": [
    {
      "channel": "whatsapp",
      "to": "447700900000"
    }
  ],
  "locale": "es-es",
  "channel_timeout": 300,
  "client_ref": "my-personal-reference",
  "code_length": 4
}

Example Request » WhatsApp-Interactive

{
  "brand": "ACME, Inc",
  "workflow": [
    {
      "channel": "whatsapp_interactive",
      "to": "447700900000"
    }
  ]
}
{
  "brand": "ACME, Inc",
  "workflow": [
    {
      "channel": "whatsapp_interactive",
      "to": "447700900000"
    }
  ],
  "locale": "es-es",
  "channel_timeout": 300,
  "client_ref": "my-personal-reference",
  "code_length": 4
}

Example Request » Voice

{
  "brand": "ACME, Inc",
  "workflow": [
    {
      "channel": "voice",
      "to": "447700900000"
    }
  ]
}
{
  "brand": "ACME, Inc",
  "workflow": [
    {
      "channel": "voice",
      "to": "447700900000"
    }
  ],
  "locale": "es-es",
  "channel_timeout": 300,
  "client_ref": "my-personal-reference",
  "code_length": 4
}

Example Responses

202 422 429
{
  "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315"
}
{
  "title": "Invalid params",
  "detail": "The value of one or more parameters is invalid",
  "instance": "06032957-99ce-41ee-978b-9a390cd5a89b",
  "invalid_parameters": {
    "name": "brand",
    "reason": "Brand is required"
  }
}
{
  "title": "Rate Limit Hit",
  "detail": "Please wait, then retry your request",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}

Check a supplied code against a request to see if it is valid

Allows a code to be checked against an existing Verification request

POST https://api.nexmo.com/v2/verify/:request_id
Host https://api.nexmo.com
POST /v2/verify/:request_id

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key Description Example Default
Authorization Your JSON web token.
Read more about JWTs
Bearer <JWT> None
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

request_id
string | Required

ID of the verify request

Request body application/json

code
string | Required | Min: 4 | Max: 10

The code the user supplied

Example Request

{
  "code": 1234
}

Example Responses

200 400 404 409 410 429

This endpoint does not support application/json

{
  "title": "Invalid Code",
  "detail": "The code you provided does not match the expected value.",
  "instance": "xxx"
}
{
  "type": "https://developer.vonage.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "Request  was not found or it has been verified already.",
  "instance": "xxx"
}
{
  "title": "Conflict",
  "detail": "The current Verify workflow step does not support a code.",
  "instance": "xxx"
}
{
  "title": "Invalid Code",
  "detail": "An incorrect code has been provided too many times. Workflow terminated.",
  "instance": "xxx"
}
{
  "title": "Rate Limit Hit",
  "detail": "Please wait, then retry your request",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}

Webhooks

Webhooks are an extension of an API, but instead of your code requesting data, the API sends data to you. The data arrives in a web request to your application.

To learn more about webhooks, see our webhooks documentation

This API may send any of the webhooks documented below to the URL that you have configured. You must respond with a 200 or 204 HTTP response, or the requests will be retried

 

Request status update Webhook

An inbound status update for a particular request.

POST https://example.com/webhooks/request-status-update

Request body application/json

request_id
string | Required

The ID of the request

submitted_at
string | Required

The date and time the verification request was submitted, in ISO 8601 format.

status
string | Required

Current status of this request

One of: completed, failed or expired
type
string | Required

Type of response

channel_timeout
integer | Required

The number of seconds before the current step in the verification request times out.

workflow
array of objects | Required
channel
string

The channel

One of: sms, whatsapp, whatsapp_interactive or voice
initiated_at
string

The date and time the current step in the verification request was initiated, in ISO 8601 format.

status
string

Current status of this request

One of: unused, completed, failed, expired or user_rejected
price
number

The total cost for this request so far, in EUR. This number may update as the request progresses.

finalized_at
string | Required

The date and time the verification request was completed. This response parameter is in ISO 8601 format.

Example Payload

{
  "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
  "submitted_at": "2020-01-01T14:00:00.000Z",
  "status": "completed",
  "type": "summary",
  "channel_timeout": 300,
  "workflow": [
    {
      "channel": "sms",
      "initiated_at": "2020-01-01T14:00:00.000Z",
      "status": "expired"
    },
    {
      "channel": "whatsapp",
      "initiated_at": "2020-01-01T14:02:00.000Z",
      "status": "completed"
    },
    {
      "channel": "voice",
      "initiated_at": "2020-01-01T15:05:00.000Z",
      "status": "unused"
    }
  ],
  "finalized_at": "2020-01-01T14:00:00.000Z"
}

Events Callback Webhook

An inbound events webhook.

POST https://example.com/webhooks/events-callback

Request body application/json

request_id
string | Required

The ID of the request

triggered_at
string | Required

The date and time the verification request was triggered, in ISO 8601 format.

type
string | Required

Type of response

channel
string | Required

The channel

status
string | Required

Current status of this request

One of: completed, failed, user_rejected or rejected
finalized_at
string | Required

The date and time the verification request was completed. This response parameter is in ISO 8601 format.

Example Payload

{
  "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
  "triggered_at": "2020-01-01T14:00:00.000Z",
  "type": "event",
  "channel": "whatsapp_interactive",
  "status": "completed",
  "finalized_at": "2020-01-01T14:00:00.000Z"
}