Verify API

Versão 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.

Baixar a especificação OpenAPI

Verify

Provides 2FA authentication for end-users.

Operações disponíveis

Request a verification be sent to a user

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

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

Autenticação

Esta API oferece suporte tanto à autenticação JWT quanto à autenticação básica. A autenticação básica é mais fácil de começar a usar, mas não oferece suporte a recursos avançados, como ACLs.

Você pode usar ou a autenticação JWT ou a autenticação básica, mas não ambas ao mesmo tempo.

Chave	Descrição	Onde	Exemplo
Authorization	Seu token JSON da Web. Saiba mais sobre os JWTs	Headers	`Bearer <JWT>`
Authorization	Chave e segredo da API codificados em Base64, separados por dois pontos. Leia mais	Headers	`Basic <base64>`
	HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Corpo da solicitação
Tipo de conteúdo
application/json

locale

string

Padrãoen-us

exemploes-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

Mín.15

Max900

Padrão180

exemplo180

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

Mín.1

Max40

exemplomyPersonalRef

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

code_length

integer

Padrão4

exemplo4

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

Deve ser uma das seguintes opções:45678910

code

string

Mín.4

Max10

exemploe4dR1Qz

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. If you provide a custom code, you must complete the verification flow by calling the /check endpoint with that PIN. For additional details, refer to the documentation.

brand

string

Mín.1

Max18

exemploACME

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

exemplo4ed3027d-8762-44a0-aa3f-c393717413a4

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

fraud_check

boolean

exemplotrue

Enables fraud checking for the verification request. When set to true, the request is checked against fraud detection rules and may be blocked if identified as fraudulent. This feature requires an account capability — contact support to enable it on your account.

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

Um dos

channel

string

Obrigatório

exemplosilent_auth

The channel

Deve ser uma das seguintes opções:silent_auth

string

Obrigatório

Mín.1

Max50

exemplo447700900000

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

exemplohttps://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.

coverage_check

boolean

Padrãotrue

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.

mode

string

Padrãostandard

exemploadvanced

An optional parameter to specify whether to use Silent Authentication Advanced.

Deve ser uma das seguintes opções:standardadvanced

Exemplo Solicitação

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

Respostas
Tipo de conteúdo
application/json

The request was started

request_id

string

Obrigatório

exemploc11236f4-00bf-4b89-84ba-88b25df97315

The ID of the request

check_url

string

exemplohttps://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.

Exemplo Resposta

{
   "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

Autenticação

Você pode usar ou a autenticação JWT ou a autenticação básica, mas não ambas ao mesmo tempo.

Chave	Descrição	Onde	Exemplo
Authorization	Seu token JSON da Web. Saiba mais sobre os JWTs	Headers	`Bearer <JWT>`
Authorization	Chave e segredo da API codificados em Base64, separados por dois pontos. Leia mais	Headers	`Basic <base64>`
	HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Caminho Parâmetros

request_id

string

Obrigatório

ID of the verify request

Corpo da solicitação
Tipo de conteúdo
application/json

Um dos

code

string

Obrigatório

Mín.4

Max10

exemplo1234

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

Exemplo Solicitação

{
   "code": "1234"
}

Respostas
Tipo de conteúdo
application/json

request_id

string

exemplo90596ac8-e1f1-46a9-a80f-ebd55e2296ae

status

string

exemplocompleted

Exemplo Resposta

{
   "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

Autenticação

Você pode usar ou a autenticação JWT ou a autenticação básica, mas não ambas ao mesmo tempo.

Chave	Descrição	Onde	Exemplo
Authorization	Seu token JSON da Web. Saiba mais sobre os JWTs	Headers	`Bearer <JWT>`
Authorization	Chave e segredo da API codificados em Base64, separados por dois pontos. Leia mais	Headers	`Basic <base64>`
	HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Caminho Parâmetros

request_id

string

Obrigatório

ID of the verify request

Respostas

No content

Next workflow

Move the request onto the next workflow, if available.

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

Autenticação

Você pode usar ou a autenticação JWT ou a autenticação básica, mas não ambas ao mesmo tempo.

Chave	Descrição	Onde	Exemplo
Authorization	Seu token JSON da Web. Saiba mais sobre os JWTs	Headers	`Bearer <JWT>`
Authorization	Chave e segredo da API codificados em Base64, separados por dois pontos. Leia mais	Headers	`Basic <base64>`
	HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Caminho Parâmetros

request_id

string

Obrigatório

ID of the verify request

Respostas

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

Caminho Parâmetros

request_id

string

Obrigatório

ID of the verify request

Respostas
Tipo de conteúdo
application/json

Carrier Success

request_id

string

exemploc11236f4-00bf-4b89-84ba-88b25df9731

code

string

exemplosi9sfG

Exemplo Resposta

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

Templates

Create and modify custom templates in Verify

Operações disponíveis

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

Autenticação

Você pode usar ou a autenticação JWT ou a autenticação básica, mas não ambas ao mesmo tempo.

Chave	Descrição	Onde	Exemplo
Authorization	Seu token JSON da Web. Saiba mais sobre os JWTs	Headers	`Bearer <JWT>`
Authorization	Chave e segredo da API codificados em Base64, separados por dois pontos. Leia mais	Headers	`Basic <base64>`
	HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Consulta Parâmetros

page_size

integer

Amount of templates per page

page

integer

The page number

Respostas
Tipo de conteúdo
application/json

page_size

integer

Obrigatório

exemplo1

How many items in page

page

integer

Obrigatório

exemplo2

The current page number

total_pages

integer

Obrigatório

exemplo10

Count of pages

total_items

integer

Obrigatório

exemplo25

Total amount of all templates

_embedded

object

Obrigatório

templates

array

List of templates

template_id

string(uuid)

Obrigatório

exemplo8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9

name

string

Obrigatório

exemplomy-template

is_default

boolean

Obrigatório

exemplotrue

_links

object

Obrigatório

self

object

href

string(uri)

Obrigatório

Target URL

fragments

object

href

string(uri)

Obrigatório

Target URL

_links

object

Obrigatório

self

object

href

string(uri)

Obrigatório

Target URL

object

href

string(uri)

Obrigatório

Target URL

object

href

string(uri)

Obrigatório

Target URL

first

object

href

string(uri)

Obrigatório

Target URL

last

object

href

string(uri)

Obrigatório

Target URL

Exemplo Resposta

{
   "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

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

Autenticação

Você pode usar ou a autenticação JWT ou a autenticação básica, mas não ambas ao mesmo tempo.

Chave	Descrição	Onde	Exemplo
Authorization	Seu token JSON da Web. Saiba mais sobre os JWTs	Headers	`Bearer <JWT>`
Authorization	Chave e segredo da API codificados em Base64, separados por dois pontos. Leia mais	Headers	`Basic <base64>`
	HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Corpo da solicitação
Tipo de conteúdo
application/json

name

Obrigatório

Mín.1

Max64

exemplomy-template

Reference name for template.

Exemplo Solicitação

{
   "name": "my-template"
}

Respostas
Tipo de conteúdo
application/json

template_id

string(uuid)

Obrigatório

exemplo8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9

name

string

Obrigatório

exemplomy-template

is_default

boolean

Obrigatório

exemplotrue

_links

object

Obrigatório

self

object

href

string(uri)

Obrigatório

Target URL

fragments

object

href

string(uri)

Obrigatório

Target URL

Exemplo Resposta

{
   "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

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

Autenticação

Você pode usar ou a autenticação JWT ou a autenticação básica, mas não ambas ao mesmo tempo.

Chave	Descrição	Onde	Exemplo
Authorization	Seu token JSON da Web. Saiba mais sobre os JWTs	Headers	`Bearer <JWT>`
Authorization	Chave e segredo da API codificados em Base64, separados por dois pontos. Leia mais	Headers	`Basic <base64>`
	HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Caminho Parâmetros

template_id

string

Obrigatório

The template UUID

Respostas
Tipo de conteúdo
application/json

template_id

string(uuid)

Obrigatório

exemplo8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9

name

string

Obrigatório

exemplomy-template

is_default

boolean

Obrigatório

exemplotrue

_links

object

Obrigatório

self

object

href

string(uri)

Obrigatório

Target URL

fragments

object

href

string(uri)

Obrigatório

Target URL

Exemplo Resposta

{
   "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

Autenticação

Você pode usar ou a autenticação JWT ou a autenticação básica, mas não ambas ao mesmo tempo.

Chave	Descrição	Onde	Exemplo
Authorization	Seu token JSON da Web. Saiba mais sobre os JWTs	Headers	`Bearer <JWT>`
Authorization	Chave e segredo da API codificados em Base64, separados por dois pontos. Leia mais	Headers	`Basic <base64>`
	HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Caminho Parâmetros

template_id

string

Obrigatório

The template UUID

Respostas

No Content

Update a template

patchhttps://api.nexmo.com/v2/verify/templates/:template_id

Autenticação

Você pode usar ou a autenticação JWT ou a autenticação básica, mas não ambas ao mesmo tempo.

Chave	Descrição	Onde	Exemplo
Authorization	Seu token JSON da Web. Saiba mais sobre os JWTs	Headers	`Bearer <JWT>`
Authorization	Chave e segredo da API codificados em Base64, separados por dois pontos. Leia mais	Headers	`Basic <base64>`
	HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Caminho Parâmetros

template_id

string

Obrigatório

The template UUID

Corpo da solicitação
Tipo de conteúdo
application/json

name

exemplomy-template

Reference name for template.

is_default

boolean

exemplotrue

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

Exemplo Solicitação

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

Respostas
Tipo de conteúdo
application/json

template_id

string(uuid)

Obrigatório

exemplo8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9

name

string

Obrigatório

exemplomy-template

is_default

boolean

Obrigatório

exemplotrue

_links

object

Obrigatório

self

object

href

string(uri)

Obrigatório

Target URL

fragments

object

href

string(uri)

Obrigatório

Target URL

Exemplo Resposta

{
   "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

Operações disponíveis

List template fragments

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

Autenticação

Você pode usar ou a autenticação JWT ou a autenticação básica, mas não ambas ao mesmo tempo.

Chave	Descrição	Onde	Exemplo
Authorization	Seu token JSON da Web. Saiba mais sobre os JWTs	Headers	`Bearer <JWT>`
Authorization	Chave e segredo da API codificados em Base64, separados por dois pontos. Leia mais	Headers	`Basic <base64>`
	HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Caminho Parâmetros

template_id

string

Obrigatório

The template UUID

Consulta Parâmetros

page_size

integer

Amount of templates per page

page

integer

The page number

Respostas
Tipo de conteúdo
application/json

page_size

integer

Obrigatório

exemplo1

How many items in page

page

integer

Obrigatório

exemplo2

The current page number

total_pages

integer

Obrigatório

exemplo10

Count of pages

total_items

integer

Obrigatório

exemplo25

Total amount of all template fragments

_embedded

object

Obrigatório

template_fragments

array

List of Fragment Templates

template_fragment_id

string

exemploc70f446e-997a-4313-a081-60a02a31dc19

ID for this template fragment

channel

string

exemplosms

Deve ser uma das seguintes opções:smsvoice

locale

string

exemploen-us

A Locale in IETF BCP 47 format

text

string

exemplo

Text 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

exemplo2023-08-30T15:20:15.17865735Z

date_created

string(date-time)

exemplo2021-08-30T20:12:15.17865735Z

_links

object

self

object

href

string(uri)

Obrigatório

Target URL

template

object

href

string(uri)

Obrigatório

Target URL

_links

object

Obrigatório

self

object

href

string(uri)

Obrigatório

Target URL

object

href

string(uri)

Obrigatório

Target URL

object

href

string(uri)

Obrigatório

Target URL

first

object

href

string(uri)

Obrigatório

Target URL

last

object

href

string(uri)

Obrigatório

Target URL

Exemplo Resposta

{
   "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

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

Autenticação

Você pode usar ou a autenticação JWT ou a autenticação básica, mas não ambas ao mesmo tempo.

Chave	Descrição	Onde	Exemplo
Authorization	Seu token JSON da Web. Saiba mais sobre os JWTs	Headers	`Bearer <JWT>`
Authorization	Chave e segredo da API codificados em Base64, separados por dois pontos. Leia mais	Headers	`Basic <base64>`
	HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Caminho Parâmetros

template_id

string

Obrigatório

The template UUID

Corpo da solicitação
Tipo de conteúdo
application/json

channel

string

Obrigatório

exemplosms

The channel name

Deve ser uma das seguintes opções:smsvoice

locale

string

Obrigatório

exemploen-us

The locale code, in lowercase

text

string

Obrigatório

exemploThe 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}

Exemplo Solicitação

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

Respostas
Tipo de conteúdo
application/json

template_fragment_id

string

exemploc70f446e-997a-4313-a081-60a02a31dc19

ID for this template fragment

channel

string

exemplosms

Deve ser uma das seguintes opções:smsvoice

locale

string

exemploen-us

A Locale in IETF BCP 47 format

text

string

exemplo

Text 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

exemplo2023-08-30T15:20:15.17865735Z

date_created

string(date-time)

exemplo2021-08-30T20:12:15.17865735Z

_links

object

self

object

href

string(uri)

Obrigatório

Target URL

template

object

href

string(uri)

Obrigatório

Target URL

Exemplo Resposta

{
   "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

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

Autenticação

Você pode usar ou a autenticação JWT ou a autenticação básica, mas não ambas ao mesmo tempo.

Chave	Descrição	Onde	Exemplo
Authorization	Seu token JSON da Web. Saiba mais sobre os JWTs	Headers	`Bearer <JWT>`
Authorization	Chave e segredo da API codificados em Base64, separados por dois pontos. Leia mais	Headers	`Basic <base64>`
	HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Caminho Parâmetros

template_id

string

Obrigatório

The template UUID

template_fragment_id

string

Obrigatório

The template fragment UUID

Respostas
Tipo de conteúdo
application/json

template_fragment_id

string

exemploc70f446e-997a-4313-a081-60a02a31dc19

ID for this template fragment

channel

string

exemplosms

Deve ser uma das seguintes opções:smsvoice

locale

string

exemploen-us

A Locale in IETF BCP 47 format

text

string

exemplo

Text 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

exemplo2023-08-30T15:20:15.17865735Z

date_created

string(date-time)

exemplo2021-08-30T20:12:15.17865735Z

_links

object

self

object

href

string(uri)

Obrigatório

Target URL

template

object

href

string(uri)

Obrigatório

Target URL

Exemplo Resposta

{
   "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

patchhttps://api.nexmo.com/v2/verify/templates/:template_id/template_fragments/:template_fragment_id

Autenticação

Você pode usar ou a autenticação JWT ou a autenticação básica, mas não ambas ao mesmo tempo.

Chave	Descrição	Onde	Exemplo
Authorization	Seu token JSON da Web. Saiba mais sobre os JWTs	Headers	`Bearer <JWT>`
Authorization	Chave e segredo da API codificados em Base64, separados por dois pontos. Leia mais	Headers	`Basic <base64>`
	HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Caminho Parâmetros

template_id

string

Obrigatório

The template UUID

template_fragment_id

string

Obrigatório

The template fragment UUID

Corpo da solicitação
Tipo de conteúdo
application/json

text

string

Obrigatório

exemploThe 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}

Exemplo Solicitação

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

Respostas
Tipo de conteúdo
application/json

template_fragment_id

string

exemploc70f446e-997a-4313-a081-60a02a31dc19

ID for this template fragment

channel

string

exemplosms

Deve ser uma das seguintes opções:smsvoice

locale

string

exemploen-us

A Locale in IETF BCP 47 format

text

string

exemplo

Text 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

exemplo2023-08-30T15:20:15.17865735Z

date_created

string(date-time)

exemplo2021-08-30T20:12:15.17865735Z

_links

object

self

object

href

string(uri)

Obrigatório

Target URL

template

object

href

string(uri)

Obrigatório

Target URL

Exemplo Resposta

{
   "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

deletehttps://api.nexmo.com/v2/verify/templates/:template_id/template_fragments/:template_fragment_id

Autenticação

Você pode usar ou a autenticação JWT ou a autenticação básica, mas não ambas ao mesmo tempo.

Chave	Descrição	Onde	Exemplo
Authorization	Seu token JSON da Web. Saiba mais sobre os JWTs	Headers	`Bearer <JWT>`
Authorization	Chave e segredo da API codificados em Base64, separados por dois pontos. Leia mais	Headers	`Basic <base64>`
	HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Caminho Parâmetros

template_id

string

Obrigatório

The template UUID

template_fragment_id

string

Obrigatório

The template fragment UUID

Respostas

No Content

Webhooks

Os webhooks são uma extensão de uma API, mas, em vez de seu código solicitar dados, é a API que envia os dados para você. Os dados chegam por meio de uma solicitação da web ao seu aplicativo.

Para saber mais sobre webhooks, consulte nosso artigo “ documentação sobre webhooks ”.

Esta API pode enviar qualquer um dos webhooks documentados abaixo para a URL que você configurou. Você deve responder com uma resposta HTTP do tipo “ 200 ” ou “ 204 ”; caso contrário, as solicitações serão repetidas.

Operações disponíveis

Events Callback webhook

An inbound events webhook.

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

Corpo da solicitação
Tipo de conteúdo
application/json

request_id

string

Obrigatório

exemploc11236f4-00bf-4b89-84ba-88b25df97315

The ID of the request

triggered_at

string(date-time)

Obrigatório

exemplo2020-01-01T14:00:00.000Z

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

type

string

Obrigatório

exemploevent

Type of response

channel

string

Obrigatório

exemplosms

The channel

status

string

Obrigatório

exemplocompleted

Current status of this request

Deve ser uma das seguintes opções:completedfaileduser_rejectedrejected

finalized_at

string(date-time)

Obrigatório

exemplo2020-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

exemplomy-personal-ref

Contains the client reference given in the original Verify request.

Exemplo Carga útil

{
   "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"
}

Silent Auth Request Update webhook

An inbound request update for an Asynchronous Silent Authentication workflow.

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

Corpo da solicitação
Tipo de conteúdo
application/json

request_id

string

Obrigatório

exemploc11236f4-00bf-4b89-84ba-88b25df97315

The ID of the request

triggered_at

string(date-time)

Obrigatório

exemplo2020-01-01T14:00:00.000Z

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

type

string

Obrigatório

exemploevent

Type of response

channel

string

Obrigatório

Deve ser uma das seguintes opções:silent_auth

status

string

Obrigatório

exemploaction_pending

Current status of this request

Deve ser uma das seguintes opções:completedfaileduser_rejectedexpiredaction_pending

action

object

type

string

Description of workflow event

Deve ser uma das seguintes opções:check

check_url

string

exemplohttps://api.nexmo.com/v2/verify/{request_id}/silent-auth/redirect

URL for Silent Auth Verify workflow completion

Exemplo Carga útil

{
   "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"
   }
}

Request status update webhook

An inbound status update for a particular request.

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

Corpo da solicitação
Tipo de conteúdo
application/json

request_id

string

Obrigatório

exemploc11236f4-00bf-4b89-84ba-88b25df97315

The ID of the request

submitted_at

string(date-time)

Obrigatório

exemplo2020-01-01T14:00:00.000Z

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

status

string

Obrigatório

exemplocompleted

Current status of this request

Deve ser uma das seguintes opções:completedfailedexpired

type

string

Obrigatório

exemplosummary

Type of response

channel_timeout

integer

Obrigatório

exemplo300

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

workflow

array

Obrigatório

channel

string

The channel

Deve ser uma das seguintes opções: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

exemplocompleted

Current status of this request

Deve ser uma das seguintes opções:unusedcompletedfailedexpireduser_rejected

client_ref

string

exemplomy-personal-ref

Contains the client reference given in the original Verify request.

Exemplo Carga útil

{
   "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"
}

Erros

A seguir, apresentamos uma lista não exaustiva de códigos de erro que podem ocorrer durante o uso desta API.

Esses códigos são adicionais aos que constam em nosso site códigos de erro genéricos.

Código	Informações
fragment-exists	Descrição A template fragment for this channel and locale already exists Resolução Change either the locale or channel to a combination not being used
template-fragment-not-found	Descrição Template Fragment not found Resolução Check the ID of the template fragment you are trying to access
template-not-found	Descrição Template not found Resolução Check the ID of the template you are trying to access
template-exists	Descrição A template with this name already exists Resolução Choose a different template name in the request
not-empty-template	Descrição The template is not empty and cannot be deleted. Please delete its fragments first Resolução Delete the individual template fragments, then try again
forbidden	Descrição Templates management is not enabled for your account Resolução Contact Vonage support to enable custom template management
expired	Descrição An incorrect code has been provided too many times. Workflow terminated. Resolução Request a new Verification
no-code	Descrição The current Verify workflow step does not support a code. Resolução Change to a valid workflow to handle your request
max-templates	Descrição An account can only have a maximum of 10 custom templates Resolução Delete a template before retrying
concurrent	Descrição Concurrent verifications to the same number are not allowed. Resolução In flight verification needs to expire, fail or be completed
invalid-code	Descrição The code you provided does not match the expected value. Resolução Retry with the correct value or fail the request
no-events	Descrição The code you provided does not match the expected value. Resolução Retry with the correct value or fail the request
request-not-found	Descrição The request ID provided could not be found. Resolução Retry with a valid request ID
msisdn-error	Descrição The device MSISDN does not match. Resolução Silent Auth will not work with this device, try a different one.
precondition-failed	Descrição Conditions for the Silent Auth request to complete have not been met. Resolução Silent Auth will not work with this device, try a different one.
network-error	Descrição The Silent Auth request could not be completed due to formatting or the carrier is not supported. Resolução Check https://developer.vonage.com/en/verify/guides/silent-auth-territories?source=verify to see if the carrier(s) used are supported.

Verify API

Verify

Operações disponíveis

Request a verification be sent to a user

Autenticação

Corpo da solicitação Tipo de conteúdoapplication/json

Exemplo Solicitação

Respostas Tipo de conteúdoapplication/json

Exemplo Resposta

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

Autenticação

Caminho Parâmetros

Corpo da solicitação Tipo de conteúdoapplication/json

Exemplo Solicitação

Respostas Tipo de conteúdoapplication/json

Exemplo Resposta

Cancel a verification.

Autenticação

Caminho Parâmetros

Respostas

Next workflow

Autenticação

Caminho Parâmetros

Respostas

Attempt Silent Authentication completion

Caminho Parâmetros

Respostas Tipo de conteúdoapplication/json

Exemplo Resposta

Templates

Operações disponíveis

List all templates

Autenticação

Consulta Parâmetros

Respostas Tipo de conteúdoapplication/json

Exemplo Resposta

Create a new template

Autenticação

Corpo da solicitação Tipo de conteúdoapplication/json

Exemplo Solicitação

Respostas Tipo de conteúdoapplication/json

Exemplo Resposta

Get a template

Autenticação

Caminho Parâmetros

Respostas Tipo de conteúdoapplication/json

Exemplo Resposta

Delete a template

Autenticação

Caminho Parâmetros

Respostas

Update a template

Autenticação

Caminho Parâmetros

Corpo da solicitação Tipo de conteúdoapplication/json

Exemplo Solicitação

Respostas Tipo de conteúdoapplication/json

Exemplo Resposta

Template Fragments

Operações disponíveis

List template fragments

Autenticação

Caminho Parâmetros

Consulta Parâmetros

Respostas Tipo de conteúdoapplication/json

Exemplo Resposta

Create a template fragment

Autenticação

Caminho Parâmetros

Corpo da solicitação Tipo de conteúdoapplication/json

Exemplo Solicitação

Respostas Tipo de conteúdoapplication/json

Exemplo Resposta

Get a template fragment

Autenticação

Caminho Parâmetros

Respostas Tipo de conteúdoapplication/json

Exemplo Resposta

Update a template fragment

Autenticação

Caminho Parâmetros

Corpo da solicitação
Tipo de conteúdo
application/json

Respostas
Tipo de conteúdo
application/json

Corpo da solicitação
Tipo de conteúdo
application/json

Respostas
Tipo de conteúdo
application/json

Respostas
Tipo de conteúdo
application/json

Respostas
Tipo de conteúdo
application/json

Corpo da solicitação
Tipo de conteúdo
application/json

Respostas
Tipo de conteúdo
application/json

Respostas
Tipo de conteúdo
application/json

Corpo da solicitação
Tipo de conteúdo
application/json

Respostas
Tipo de conteúdo
application/json

Respostas
Tipo de conteúdo
application/json

Corpo da solicitação
Tipo de conteúdo
application/json

Respostas
Tipo de conteúdo
application/json

Respostas
Tipo de conteúdo
application/json

Corpo da solicitação
Tipo de conteúdo
application/json

Respostas
Tipo de conteúdo
application/json

Corpo da solicitação
Tipo de conteúdo
application/json

Corpo da solicitação
Tipo de conteúdo
application/json

Corpo da solicitação
Tipo de conteúdo
application/json