Verify API

Version 2

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.

Download OpenAPI Specification

Verify

Provides 2FA authentication for end-users.

Available Operations

Request a verification be sent to a user

Start the verification process to a given channel(s).

posthttps://api.nexmo.com/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.

KeyDescriptionWhereExample
Authorization

Your JSON web token.
Read more about JWTs

Headers

Bearer <JWT>
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>
HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Request Body
Content Type
application/json

locale
string
Defaulten-us
examplees-es

Languages that are available to use. See the full list of supported languages in the Verify Languages Guide. It has no effect if the channel is silent_auth.

channel_timeout
integer
Min15
Max900
Default180
example180

Specifies the wait time in seconds between attempts to deliver the verification code. On the Verify Success pricing model, the minimum channel_timeout is fixed at 60 seconds and cannot be changed; and if you are using Silent Authentication, the channel_timeout is always fixed at 60 seconds, irrespective of the pricing model.

client_ref
string
Min1
Max40
examplemyPersonalRef

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

code_length
integer
Default4
example4

Length of the code to send to the user. It applies to all channels defined in the workflow.

Must be one of:45678910
code
string
Min4
Max10
examplee4dR1Qz

An optional alphanumeric custom code to use if you don't want Vonage to generate the code. Only the Verify Conversion pricing model allows using this parameter, and it has no effect if the channel is silent_auth.

brand
string
Min1
Max18
exampleACME

The brand that is sending the verification request. Please note that for security reasons, the following regex is used to escape this value: ^[^\/{}:$]*$. A value that fails this check will result in a 422.

template_id
string
example4ed3027d-8762-44a0-aa3f-c393717413a4

A custom template ID to use. This parameter works only when channel is sms or rcs.

workflow
array

Defines the sequence of actions (max 3) that Vonage uses to reach the end-user you want to verify with a PIN code. See documentation

One Of
channel
string
Required
examplesilent_auth

The channel

Must be one of:silent_auth
to
string
Required
Min1
Max50
example447700900000

The phone number to use for authentication, 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.

redirect_url
string
examplehttps://acme-app.com/sa/redirect

Optional final redirect added at the end of the check_url request/response lifecycle. See the documentation for integrations. Will contain the request_id and code as a url fragment after the URL.

sandbox
boolean
exampletrue

Optional parameter if you are using the Vonage Sandbox to test Silent Auth integrations.

coverage_check
boolean
Defaulttrue

Controls network coverage lookup. If true, a synchronous error is returned when the network is unsupported. If false a check_url is always returned and errors are reported via callbacks.

Example Request

{
   "locale": "es-es",
   "channel_timeout": 180,
   "client_ref": "myPersonalRef",
   "code_length": 4,
   "code": "e4dR1Qz",
   "brand": "ACME",
   "template_id": "4ed3027d-8762-44a0-aa3f-c393717413a4",
   "workflow": [
      {
         "channel": "silent_auth",
         "to": "44770090000",
         "redirect_url": "https://acme-app.com/sa/redirect"
      },
      {
         "channel": "sms",
         "to": "44770090000"
      },
      {
         "channel": "voice",
         "to": "44770090000"
      }
   ]
}

Responses
Content Type
application/json

The request was started

request_id
string
Required
examplec11236f4-00bf-4b89-84ba-88b25df97315

The ID of the request

check_url
string
examplehttps://api.nexmo.com/v2/verify/c11236f4-00bf-4b89-84ba-88b25df97315/silent-auth/redirect

The URL to complete the Silent Authentication verification process. It is returned only when Silent Auth is the initial verification channel in the workflow and the network supports it, unless coverage_check is set to false. See the documentation for supported network availability.

Example Response

{
   "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
   "check_url": "https://api.nexmo.com/v2/verify/c11236f4-00bf-4b89-84ba-88b25df97315/silent-auth/redirect"
}

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

Allows a code to be checked against an existing Verification request.

Note on using Silent Authentication:

If you are checking a code against a Silent Authentication workflow, you will only have one attempt to submit the code, as this should be handled by a Client SDK.
posthttps://api.nexmo.com/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.

KeyDescriptionWhereExample
Authorization

Your JSON web token.
Read more about JWTs

Headers

Bearer <JWT>
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>
HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Path Parameters

request_id
string
Required

ID of the verify request

Request Body
Content Type
application/json

code
string
Required
Min4
Max10
example1234

The code provided by the user. The PIN code can be retried a maximum of three times.

Example Request

{
   "code": "1234"
}

Responses
Content Type
application/json

OK

request_id
string
example90596ac8-e1f1-46a9-a80f-ebd55e2296ae
status
string
examplecompleted

Example Response

{
   "request_id": "90596ac8-e1f1-46a9-a80f-ebd55e2296ae",
   "status": "completed"
}

Cancel a verification.

If a verification request is still active, it aborts the workflow.

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.

deletehttps://api.nexmo.com/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.

KeyDescriptionWhereExample
Authorization

Your JSON web token.
Read more about JWTs

Headers

Bearer <JWT>
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>
HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Path Parameters

request_id
string
Required

ID of the verify request

Responses

No content

Next workflow

Move the request onto the next workflow, if available.

posthttps://api.nexmo.com/v2/verify/:request_id/next_workflow

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.

KeyDescriptionWhereExample
Authorization

Your JSON web token.
Read more about JWTs

Headers

Bearer <JWT>
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>
HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Path Parameters

request_id
string
Required

ID of the verify request

Responses

OK

Attempt Silent Authentication completion

This is a URL that is returned from a new Silent Authentication request as check_url (or can also be obtained from the Silent Authentication webhook event, if your integration is asynchronous.) Performing a GET request on the URL provided will return a series of 30x redirects to follow. Following these 30xs will result in either success containing a code to submit or an error.

Note on Cellular Usage:

This URL (i.e. the `check_url`) must be hit by a device using cellular data in order for Silent Authentication to work correctly.
Note that errors will also be included as a fragment within the URL for the frontend to parse. These will take the following example format:

https:\\example.com\silent-auth\your-callback-route#error_description=The silent auth verification cannot be completed.

The possible error messages are as follows:
  • The silent auth verification cannot be completed.
  • Device MSISDN does not match.
  • Device number does not resolve to a supported Mobile Network Operator.
  • IP Address does not resolve to a cellular device.
gethttps://api.nexmo.com/v2/verify/:request_id/silent-auth/redirect

Path Parameters

request_id
string
Required

ID of the verify request

Responses
Content Type
application/json

Carrier Success

request_id
string
examplec11236f4-00bf-4b89-84ba-88b25df9731
code
string
examplesi9sfG

Example Response

{
   "request_id": "c11236f4-00bf-4b89-84ba-88b25df9731",
   "code": "si9sfG"
}

Templates

Create and modify custom templates in Verify

Available Operations

List all templates

Note on using Custom Templates:

Writing Custom Templates is only possible if your account has been enabled to do so. You can, however, view your templates. Please contact Support to enable this.
Custom Template functionality is currently in Beta
gethttps://api.nexmo.com/v2/verify/templates

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.

KeyDescriptionWhereExample
Authorization

Your JSON web token.
Read more about JWTs

Headers

Bearer <JWT>
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>
HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Query Parameters

page_size
integer

Amount of templates per page

page
integer

The page number

Responses
Content Type
application/json

OK

page_size
integer
Required
example1

How many items in page

page
integer
Required
example2

The current page number

total_pages
integer
Required
example10

Count of pages

total_items
integer
Required
example25

Total amount of all templates

_embedded
object
Required
templates
array

List of templates

template_id
string(uuid)
Required
example8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9
name
string
Required
examplemy-template
is_default
boolean
Required
exampletrue
_links
object
Required
self
object
href
string(uri)
Required

Target URL

fragments
object
href
string(uri)
Required

Target URL

_links
object
Required
self
object
href
string(uri)
Required

Target URL

next
object
href
string(uri)
Required

Target URL

prev
object
href
string(uri)
Required

Target URL

first
object
href
string(uri)
Required

Target URL

last
object
href
string(uri)
Required

Target URL

Example Response

{
   "page_size": 1,
   "page": 2,
   "total_pages": 10,
   "total_items": 25,
   "_embedded": {
      "templates": [
         {
            "template_id": "8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9",
            "name": "my-template",
            "is_default": true,
            "_links": {
               "self": {
                  "href": "http://example.com"
               },
               "fragments": {
                  "href": "http://example.com"
               }
            }
         }
      ]
   },
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v2/verify/templates?page=2"
      },
      "next": {
         "href": "https://api.nexmo.com/v2/verify/templates?page=3"
      },
      "prev": {
         "href": "https://api.nexmo.com/v2/verify/templates?page=1"
      },
      "last": {
         "href": "https://api.nexmo.com/v2/verify/templates?page=5"
      }
   }
}

Create a new template

Create a new template

posthttps://api.nexmo.com/v2/verify/templates

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.

KeyDescriptionWhereExample
Authorization

Your JSON web token.
Read more about JWTs

Headers

Bearer <JWT>
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>
HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Request Body
Content Type
application/json

name
Required
Min1
Max64
examplemy-template

Reference name for template.

Example Request

{
   "name": "my-template"
}

Responses
Content Type
application/json

OK

template_id
string(uuid)
Required
example8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9
name
string
Required
examplemy-template
is_default
boolean
Required
exampletrue
_links
object
Required
self
object
href
string(uri)
Required

Target URL

fragments
object
href
string(uri)
Required

Target URL

Example Response

{
   "template_id": "8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9",
   "name": "my-template",
   "is_default": true,
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v2/verify/templates/8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9"
      },
      "fragments": {
         "href": "https://api.nexmo.com/v2/verify/templates/8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9/template_fragments"
      }
   }
}

Get a template

Get a template

gethttps://api.nexmo.com/v2/verify/templates/:template_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.

KeyDescriptionWhereExample
Authorization

Your JSON web token.
Read more about JWTs

Headers

Bearer <JWT>
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>
HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Path Parameters

template_id
string
Required

The template UUID

Responses
Content Type
application/json

OK

template_id
string(uuid)
Required
example8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9
name
string
Required
examplemy-template
is_default
boolean
Required
exampletrue
_links
object
Required
self
object
href
string(uri)
Required

Target URL

fragments
object
href
string(uri)
Required

Target URL

Example Response

{
   "template_id": "8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9",
   "name": "my-template",
   "is_default": true,
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v2/verify/templates/8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9"
      },
      "fragments": {
         "href": "https://api.nexmo.com/v2/verify/templates/8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9/template_fragments"
      }
   }
}

Delete a template

Note that a template can only be deleted if there are no template fragments attached to it.

deletehttps://api.nexmo.com/v2/verify/templates/:template_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.

KeyDescriptionWhereExample
Authorization

Your JSON web token.
Read more about JWTs

Headers

Bearer <JWT>
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>
HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Path Parameters

template_id
string
Required

The template UUID

Responses

No Content

Update a template

Update a template

patchhttps://api.nexmo.com/v2/verify/templates/:template_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.

KeyDescriptionWhereExample
Authorization

Your JSON web token.
Read more about JWTs

Headers

Bearer <JWT>
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>
HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Path Parameters

template_id
string
Required

The template UUID

Request Body
Content Type
application/json

name
examplemy-template

Reference name for template.

is_default
boolean
exampletrue

Whether the template is the default template if a new request does not specify a template to use.

Example Request

{
   "name": "my-template",
   "is_default": true
}

Responses
Content Type
application/json

OK

template_id
string(uuid)
Required
example8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9
name
string
Required
examplemy-template
is_default
boolean
Required
exampletrue
_links
object
Required
self
object
href
string(uri)
Required

Target URL

fragments
object
href
string(uri)
Required

Target URL

Example Response

{
   "template_id": "8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9",
   "name": "my-template",
   "is_default": true,
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v2/verify/templates/8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9"
      },
      "fragments": {
         "href": "https://api.nexmo.com/v2/verify/templates/8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9/template_fragments"
      }
   }
}

Template Fragments

Create and modify custom template fragments in Verify

Available Operations

List template fragments

List template fragments

gethttps://api.nexmo.com/v2/verify/templates/:template_id/template_fragments

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.

KeyDescriptionWhereExample
Authorization

Your JSON web token.
Read more about JWTs

Headers

Bearer <JWT>
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>
HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Path Parameters

template_id
string
Required

The template UUID

Query Parameters

page_size
integer

Amount of templates per page

page
integer

The page number

Responses
Content Type
application/json

OK

page_size
integer
Required
example1

How many items in page

page
integer
Required
example2

The current page number

total_pages
integer
Required
example10

Count of pages

total_items
integer
Required
example25

Total amount of all template fragments

_embedded
object
Required
template_fragments
array

List of Fragment Templates

template_fragment_id
string
examplec70f446e-997a-4313-a081-60a02a31dc19

ID for this template fragment

channel
string
examplesms
Must be one of:smsvoice
locale
string
exampleen-us

A Locale in IETF BCP 47 format

text
string
exampleText content of the template. May contain 4 reserved variables: `${code}`, `${brand}`, `${time-limit}` and `${time-limit-unit}`

Text content of the template

date_updated
string
example2023-08-30T15:20:15.17865735Z
date_created
string(date-time)
example2021-08-30T20:12:15.17865735Z
_links
object
self
object
href
string(uri)
Required

Target URL

template
object
href
string(uri)
Required

Target URL

_links
object
Required
self
object
href
string(uri)
Required

Target URL

next
object
href
string(uri)
Required

Target URL

prev
object
href
string(uri)
Required

Target URL

first
object
href
string(uri)
Required

Target URL

last
object
href
string(uri)
Required

Target URL

Example Response

{
   "page_size": 1,
   "page": 2,
   "total_pages": 10,
   "total_items": 25,
   "_embedded": {
      "template_fragments": [
         {
            "template_fragment_id": "c70f446e-997a-4313-a081-60a02a31dc19",
            "channel": "sms",
            "locale": "en-us",
            "text": "Text content of the template. May contain 4 reserved variables: `${code}`, `${brand}`, `${time-limit}` and `${time-limit-unit}`",
            "date_updated": "2023-08-30T15:20:15.17865735Z",
            "date_created": "2021-08-30T20:12:15.17865735Z",
            "_links": {
               "self": {
                  "href": "http://example.com"
               },
               "template": {
                  "href": "http://example.com"
               }
            }
         }
      ]
   },
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v2/verify/templates?page=2"
      },
      "next": {
         "href": "https://api.nexmo.com/v2/verify/templates?page=3"
      },
      "prev": {
         "href": "https://api.nexmo.com/v2/verify/templates?page=1"
      },
      "last": {
         "href": "https://api.nexmo.com/v2/verify/templates?page=5"
      }
   }
}

Create a template fragment

Create a template fragment

posthttps://api.nexmo.com/v2/verify/templates/:template_id/template_fragments

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.

KeyDescriptionWhereExample
Authorization

Your JSON web token.
Read more about JWTs

Headers

Bearer <JWT>
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>
HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Path Parameters

template_id
string
Required

The template UUID

Request Body
Content Type
application/json

channel
string
Required
examplesms

The channel name

Must be one of:smsvoice
locale
string
Required
exampleen-us

The locale code, in lowercase

text
string
Required
exampleThe authentication code for your ${brand} is: ${code}

The template text. There are 4 reserved variables available to use: ${code}, ${brand}, ${time-limit} and ${time-limit-unit}

Example Request

{
   "channel": "sms",
   "locale": "en-us",
   "text": "The authentication code for your ${brand} is: ${code}"
}

Responses
Content Type
application/json

OK

template_fragment_id
string
examplec70f446e-997a-4313-a081-60a02a31dc19

ID for this template fragment

channel
string
examplesms
Must be one of:smsvoice
locale
string
exampleen-us

A Locale in IETF BCP 47 format

text
string
exampleText content of the template. May contain 4 reserved variables: `${code}`, `${brand}`, `${time-limit}` and `${time-limit-unit}`

Text content of the template

date_updated
string
example2023-08-30T15:20:15.17865735Z
date_created
string(date-time)
example2021-08-30T20:12:15.17865735Z
_links
object
self
object
href
string(uri)
Required

Target URL

template
object
href
string(uri)
Required

Target URL

Example Response

{
   "template_fragment_id": "c70f446e-997a-4313-a081-60a02a31dc19",
   "channel": "sms",
   "locale": "en-us",
   "text": "Text content of the template. May contain 4 reserved variables: `${code}`, `${brand}`, `${time-limit}` and `${time-limit-unit}`",
   "date_updated": "2023-08-30T15:20:15.17865735Z",
   "date_created": "2021-08-30T20:12:15.17865735Z",
   "_links": {
      "self": {
         "href": "http://example.com"
      },
      "template": {
         "href": "http://example.com"
      }
   }
}

Get a template fragment

Get a template fragment

gethttps://api.nexmo.com/v2/verify/templates/:template_id/template_fragments/:template_fragment_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.

KeyDescriptionWhereExample
Authorization

Your JSON web token.
Read more about JWTs

Headers

Bearer <JWT>
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>
HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Path Parameters

template_id
string
Required

The template UUID

template_fragment_id
string
Required

The template fragment UUID

Responses
Content Type
application/json

OK

template_fragment_id
string
examplec70f446e-997a-4313-a081-60a02a31dc19

ID for this template fragment

channel
string
examplesms
Must be one of:smsvoice
locale
string
exampleen-us

A Locale in IETF BCP 47 format

text
string
exampleText content of the template. May contain 4 reserved variables: `${code}`, `${brand}`, `${time-limit}` and `${time-limit-unit}`

Text content of the template

date_updated
string
example2023-08-30T15:20:15.17865735Z
date_created
string(date-time)
example2021-08-30T20:12:15.17865735Z
_links
object
self
object
href
string(uri)
Required

Target URL

template
object
href
string(uri)
Required

Target URL

Example Response

{
   "template_fragment_id": "c70f446e-997a-4313-a081-60a02a31dc19",
   "channel": "sms",
   "locale": "en-us",
   "text": "Text content of the template. May contain 4 reserved variables: `${code}`, `${brand}`, `${time-limit}` and `${time-limit-unit}`",
   "date_updated": "2023-08-30T15:20:15.17865735Z",
   "date_created": "2021-08-30T20:12:15.17865735Z",
   "_links": {
      "self": {
         "href": "http://example.com"
      },
      "template": {
         "href": "http://example.com"
      }
   }
}

Update a template fragment

Update a template fragment

patchhttps://api.nexmo.com/v2/verify/templates/:template_id/template_fragments/:template_fragment_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.

KeyDescriptionWhereExample
Authorization

Your JSON web token.
Read more about JWTs

Headers

Bearer <JWT>
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>
HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Path Parameters

template_id
string
Required

The template UUID

template_fragment_id
string
Required

The template fragment UUID

Request Body
Content Type
application/json

text
string
Required
exampleThe authentication code for your ${brand} is: ${code}

The template text. There are 4 reserved variables available to use: ${code}, ${brand}, ${time-limit} and ${time-limit-unit}

Example Request

{
   "text": "The authentication code for your ${brand} is: ${code}"
}

Responses
Content Type
application/json

OK

template_fragment_id
string
examplec70f446e-997a-4313-a081-60a02a31dc19

ID for this template fragment

channel
string
examplesms
Must be one of:smsvoice
locale
string
exampleen-us

A Locale in IETF BCP 47 format

text
string
exampleText content of the template. May contain 4 reserved variables: `${code}`, `${brand}`, `${time-limit}` and `${time-limit-unit}`

Text content of the template

date_updated
string
example2023-08-30T15:20:15.17865735Z
date_created
string(date-time)
example2021-08-30T20:12:15.17865735Z
_links
object
self
object
href
string(uri)
Required

Target URL

template
object
href
string(uri)
Required

Target URL

Example Response

{
   "template_fragment_id": "c70f446e-997a-4313-a081-60a02a31dc19",
   "channel": "sms",
   "locale": "en-us",
   "text": "Text content of the template. May contain 4 reserved variables: `${code}`, `${brand}`, `${time-limit}` and `${time-limit-unit}`",
   "date_updated": "2023-08-30T15:20:15.17865735Z",
   "date_created": "2021-08-30T20:12:15.17865735Z",
   "_links": {
      "self": {
         "href": "http://example.com"
      },
      "template": {
         "href": "http://example.com"
      }
   }
}

Delete a template fragment

Delete a template fragment

deletehttps://api.nexmo.com/v2/verify/templates/:template_id/template_fragments/:template_fragment_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.

KeyDescriptionWhereExample
Authorization

Your JSON web token.
Read more about JWTs

Headers

Bearer <JWT>
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>
HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Path Parameters

template_id
string
Required

The template UUID

template_fragment_id
string
Required

The template fragment UUID

Responses

No Content

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.

Available Operations

Events Callback webhook

An inbound events webhook.

posthttps://example.com/webhooks/events-callback

Request Body
Content Type
application/json

request_id
string
Required
examplec11236f4-00bf-4b89-84ba-88b25df97315

The ID of the request

triggered_at
string(date-time)
Required
example2020-01-01T14:00:00.000Z

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

type
string
Required
exampleevent

Type of response

channel
string
Required
examplesms

The channel

status
string
Required
examplecompleted

Current status of this request

Must be one of:completedfaileduser_rejectedrejected
finalized_at
string(date-time)
Required
example2020-01-01T14:00:00.000Z

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

client_ref
string
examplemy-personal-ref

Contains the client reference given in the original Verify request.

Example Payload

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

Request status update webhook

An inbound status update for a particular request.

posthttps://example.com/webhooks/request-status-update

Request Body
Content Type
application/json

request_id
string
Required
examplec11236f4-00bf-4b89-84ba-88b25df97315

The ID of the request

submitted_at
string(date-time)
Required
example2020-01-01T14:00:00.000Z

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

status
string
Required
examplecompleted

Current status of this request

Must be one of:completedfailedexpired
type
string
Required
examplesummary

Type of response

channel_timeout
integer
Required
example300

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

workflow
array
Required
channel
string

The channel

Must be one of:smswhatsappvoicesilent_auth
initiated_at
string(date-time)

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

status
string
examplecompleted

Current status of this request

Must be one of:unusedcompletedfailedexpireduser_rejected
client_ref
string
examplemy-personal-ref

Contains the client reference given in the original Verify request.

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": "silent_auth",
         "initiated_at": "2020-01-01T14:00:00.000Z",
         "status": "expired"
      },
      {
         "channel": "sms",
         "initiated_at": "2020-01-01T14:02:00.000Z",
         "status": "completed"
      },
      {
         "channel": "voice",
         "initiated_at": "2020-01-01T15:05:00.000Z",
         "status": "unused"
      }
   ],
   "client_ref": "my-personal-ref"
}

Silent Auth Request Update webhook

An inbound request update for an Asynchronous Silent Authentication workflow.

posthttps://example.com/webhooks/request-status-update

Request Body
Content Type
application/json

request_id
string
Required
examplec11236f4-00bf-4b89-84ba-88b25df97315

The ID of the request

triggered_at
string(date-time)
Required
example2020-01-01T14:00:00.000Z

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

type
string
Required
exampleevent

Type of response

channel
string
Required
Must be one of:silent_auth
status
string
Required
exampleaction_pending

Current status of this request

Must be one of:completedfaileduser_rejectedexpiredaction_pending
action
array
type
string

Description of workflow event

Must be one of:check
check_url
string
examplehttps://api.nexmo.com/v2/verify/{request_id}/silent-auth/redirect

URL for Silent Auth Verify workflow completion

Example Payload

{
   "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
   "triggered_at": "2020-01-01T14:00:00.000Z",
   "type": "event",
   "channel": "silent_auth",
   "status": "action_pending",
   "action": [
      {
         "type": "check",
         "check_url": "https://api.nexmo.com/v2/verify/{request_id}/silent-auth/redirect"
      }
   ]
}

Errors

The following is a non-exhaustive list of error codes that may occur while using this API.

These codes are in addition to any of our generic error codes.

CodeInformation
fragment-exists

Description

A template fragment for this channel and locale already exists

Resolution

Change either the locale or channel to a combination not being used

template-fragment-not-found

Description

Template Fragment not found

Resolution

Check the ID of the template fragment you are trying to access

template-not-found

Description

Template not found

Resolution

Check the ID of the template you are trying to access

template-exists

Description

A template with this name already exists

Resolution

Choose a different template name in the request

not-empty-template

Description

The template is not empty and cannot be deleted. Please delete its fragments first

Resolution

Delete the individual template fragments, then try again

forbidden

Description

Templates management is not enabled for your account

Resolution

Contact Vonage support to enable custom template management

expired

Description

An incorrect code has been provided too many times. Workflow terminated.

Resolution

Request a new Verification

no-code

Description

The current Verify workflow step does not support a code.

Resolution

Change to a valid workflow to handle your request

max-templates

Description

An account can only have a maximum of 10 custom templates

Resolution

Delete a template before retrying

concurrent

Description

Concurrent verifications to the same number are not allowed.

Resolution

In flight verification needs to expire, fail or be completed

invalid-code

Description

The code you provided does not match the expected value.

Resolution

Retry with the correct value or fail the request

no-events

Description

The code you provided does not match the expected value.

Resolution

Retry with the correct value or fail the request

request-not-found

Description

The request ID provided could not be found.

Resolution

Retry with a valid request ID

msisdn-error

Description

The device MSISDN does not match.

Resolution

Silent Auth will not work with this device, try a different one.

precondition-failed

Description

Conditions for the Silent Auth request to complete have not been met.

Resolution

Silent Auth will not work with this device, try a different one.

network-error

Description

The Silent Auth request could not be completed due to formatting or the carrier is not supported.

Resolution

Check https://developer.vonage.com/en/verify/guides/silent-auth-territories?source=verify to see if the carrier(s) used are supported.