Verify API

Versión 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.

Descargar la especificación OpenAPI

Verify

Provides 2FA authentication for end-users.

Operaciones disponibles

Request a verification be sent to a user

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

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

Autenticación

Esta API admite tanto la autenticación JWT como la básica. La autenticación básica es más fácil para empezar, pero no admite funciones avanzadas como ACL.

Puede utilizar o bien la autenticación JWT o Basic, pero no ambas a la vez.

ClaveDescripciónDóndeEjemplo
Authorization

Su token web JSON.
Más información sobre los JWT

Headers

Bearer <JWT>
Authorization

Clave API codificada en Base64 y secreto unidos por dos puntos.
Seguir leyendo

Headers

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

Cuerpo de la solicitud
Tipo de contenido
application/json

locale
string
Por defectoen-us
ejemploes-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
Por defecto180
ejemplo180

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
ejemplomyPersonalRef

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

code_length
integer
Por defecto4
ejemplo4

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

Debe ser uno de:45678910
code
string
Min4
Max10
ejemploe4dR1Qz

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
Min1
Max18
ejemploACME

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

Uno de
channel
string
Requerido
ejemplosilent_auth

The channel

Debe ser uno de:silent_auth
to
string
Requerido
Min1
Max50
ejemplo447700900000

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
ejemplohttps://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
Por defectotrue

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.

Ejemplo Solicitar

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

Respuestas
Tipo de contenido
application/json

The request was started

request_id
string
Requerido
ejemploc11236f4-00bf-4b89-84ba-88b25df97315

The ID of the request

check_url
string
ejemplohttps://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.

Ejemplo Respuesta

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

Autenticación

Esta API admite tanto la autenticación JWT como la básica. La autenticación básica es más fácil para empezar, pero no admite funciones avanzadas como ACL.

Puede utilizar o bien la autenticación JWT o Basic, pero no ambas a la vez.

ClaveDescripciónDóndeEjemplo
Authorization

Su token web JSON.
Más información sobre los JWT

Headers

Bearer <JWT>
Authorization

Clave API codificada en Base64 y secreto unidos por dos puntos.
Seguir leyendo

Headers

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

Ruta Parámetros

request_id
string
Requerido

ID of the verify request

Cuerpo de la solicitud
Tipo de contenido
application/json

code
string
Requerido
Min4
Max10
ejemplo1234

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

Ejemplo Solicitar

{
   "code": "1234"
}

Respuestas
Tipo de contenido
application/json

OK

request_id
string
ejemplo90596ac8-e1f1-46a9-a80f-ebd55e2296ae
status
string
ejemplocompleted

Ejemplo Respuesta

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

Autenticación

Esta API admite tanto la autenticación JWT como la básica. La autenticación básica es más fácil para empezar, pero no admite funciones avanzadas como ACL.

Puede utilizar o bien la autenticación JWT o Basic, pero no ambas a la vez.

ClaveDescripciónDóndeEjemplo
Authorization

Su token web JSON.
Más información sobre los JWT

Headers

Bearer <JWT>
Authorization

Clave API codificada en Base64 y secreto unidos por dos puntos.
Seguir leyendo

Headers

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

Ruta Parámetros

request_id
string
Requerido

ID of the verify request

Respuestas

No content

Next workflow

Move the request onto the next workflow, if available.

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

Autenticación

Esta API admite tanto la autenticación JWT como la básica. La autenticación básica es más fácil para empezar, pero no admite funciones avanzadas como ACL.

Puede utilizar o bien la autenticación JWT o Basic, pero no ambas a la vez.

ClaveDescripciónDóndeEjemplo
Authorization

Su token web JSON.
Más información sobre los JWT

Headers

Bearer <JWT>
Authorization

Clave API codificada en Base64 y secreto unidos por dos puntos.
Seguir leyendo

Headers

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

Ruta Parámetros

request_id
string
Requerido

ID of the verify request

Respuestas

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

Ruta Parámetros

request_id
string
Requerido

ID of the verify request

Respuestas
Tipo de contenido
application/json

Carrier Success

request_id
string
ejemploc11236f4-00bf-4b89-84ba-88b25df9731
code
string
ejemplosi9sfG

Ejemplo Respuesta

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

Templates

Create and modify custom templates in Verify

Operaciones disponibles

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

Autenticación

Esta API admite tanto la autenticación JWT como la básica. La autenticación básica es más fácil para empezar, pero no admite funciones avanzadas como ACL.

Puede utilizar o bien la autenticación JWT o Basic, pero no ambas a la vez.

ClaveDescripciónDóndeEjemplo
Authorization

Su token web JSON.
Más información sobre los JWT

Headers

Bearer <JWT>
Authorization

Clave API codificada en Base64 y secreto unidos por dos puntos.
Seguir leyendo

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

Respuestas
Tipo de contenido
application/json

OK

page_size
integer
Requerido
ejemplo1

How many items in page

page
integer
Requerido
ejemplo2

The current page number

total_pages
integer
Requerido
ejemplo10

Count of pages

total_items
integer
Requerido
ejemplo25

Total amount of all templates

_embedded
object
Requerido
templates
array

List of templates

template_id
string(uuid)
Requerido
ejemplo8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9
name
string
Requerido
ejemplomy-template
is_default
boolean
Requerido
ejemplotrue
_links
object
Requerido
self
object
href
string(uri)
Requerido

Target URL

fragments
object
href
string(uri)
Requerido

Target URL

_links
object
Requerido
self
object
href
string(uri)
Requerido

Target URL

next
object
href
string(uri)
Requerido

Target URL

prev
object
href
string(uri)
Requerido

Target URL

first
object
href
string(uri)
Requerido

Target URL

last
object
href
string(uri)
Requerido

Target URL

Ejemplo Respuesta

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

Autenticación

Esta API admite tanto la autenticación JWT como la básica. La autenticación básica es más fácil para empezar, pero no admite funciones avanzadas como ACL.

Puede utilizar o bien la autenticación JWT o Basic, pero no ambas a la vez.

ClaveDescripciónDóndeEjemplo
Authorization

Su token web JSON.
Más información sobre los JWT

Headers

Bearer <JWT>
Authorization

Clave API codificada en Base64 y secreto unidos por dos puntos.
Seguir leyendo

Headers

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

Cuerpo de la solicitud
Tipo de contenido
application/json

name
Requerido
Min1
Max64
ejemplomy-template

Reference name for template.

Ejemplo Solicitar

{
   "name": "my-template"
}

Respuestas
Tipo de contenido
application/json

OK

template_id
string(uuid)
Requerido
ejemplo8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9
name
string
Requerido
ejemplomy-template
is_default
boolean
Requerido
ejemplotrue
_links
object
Requerido
self
object
href
string(uri)
Requerido

Target URL

fragments
object
href
string(uri)
Requerido

Target URL

Ejemplo Respuesta

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

Autenticación

Esta API admite tanto la autenticación JWT como la básica. La autenticación básica es más fácil para empezar, pero no admite funciones avanzadas como ACL.

Puede utilizar o bien la autenticación JWT o Basic, pero no ambas a la vez.

ClaveDescripciónDóndeEjemplo
Authorization

Su token web JSON.
Más información sobre los JWT

Headers

Bearer <JWT>
Authorization

Clave API codificada en Base64 y secreto unidos por dos puntos.
Seguir leyendo

Headers

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

Ruta Parámetros

template_id
string
Requerido

The template UUID

Respuestas
Tipo de contenido
application/json

OK

template_id
string(uuid)
Requerido
ejemplo8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9
name
string
Requerido
ejemplomy-template
is_default
boolean
Requerido
ejemplotrue
_links
object
Requerido
self
object
href
string(uri)
Requerido

Target URL

fragments
object
href
string(uri)
Requerido

Target URL

Ejemplo Respuesta

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

Autenticación

Esta API admite tanto la autenticación JWT como la básica. La autenticación básica es más fácil para empezar, pero no admite funciones avanzadas como ACL.

Puede utilizar o bien la autenticación JWT o Basic, pero no ambas a la vez.

ClaveDescripciónDóndeEjemplo
Authorization

Su token web JSON.
Más información sobre los JWT

Headers

Bearer <JWT>
Authorization

Clave API codificada en Base64 y secreto unidos por dos puntos.
Seguir leyendo

Headers

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

Ruta Parámetros

template_id
string
Requerido

The template UUID

Respuestas

No Content

Update a template

Update a template

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

Autenticación

Esta API admite tanto la autenticación JWT como la básica. La autenticación básica es más fácil para empezar, pero no admite funciones avanzadas como ACL.

Puede utilizar o bien la autenticación JWT o Basic, pero no ambas a la vez.

ClaveDescripciónDóndeEjemplo
Authorization

Su token web JSON.
Más información sobre los JWT

Headers

Bearer <JWT>
Authorization

Clave API codificada en Base64 y secreto unidos por dos puntos.
Seguir leyendo

Headers

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

Ruta Parámetros

template_id
string
Requerido

The template UUID

Cuerpo de la solicitud
Tipo de contenido
application/json

name
ejemplomy-template

Reference name for template.

is_default
boolean
ejemplotrue

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

Ejemplo Solicitar

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

Respuestas
Tipo de contenido
application/json

OK

template_id
string(uuid)
Requerido
ejemplo8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9
name
string
Requerido
ejemplomy-template
is_default
boolean
Requerido
ejemplotrue
_links
object
Requerido
self
object
href
string(uri)
Requerido

Target URL

fragments
object
href
string(uri)
Requerido

Target URL

Ejemplo Respuesta

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

Operaciones disponibles

List template fragments

List template fragments

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

Autenticación

Esta API admite tanto la autenticación JWT como la básica. La autenticación básica es más fácil para empezar, pero no admite funciones avanzadas como ACL.

Puede utilizar o bien la autenticación JWT o Basic, pero no ambas a la vez.

ClaveDescripciónDóndeEjemplo
Authorization

Su token web JSON.
Más información sobre los JWT

Headers

Bearer <JWT>
Authorization

Clave API codificada en Base64 y secreto unidos por dos puntos.
Seguir leyendo

Headers

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

Ruta Parámetros

template_id
string
Requerido

The template UUID

Consulta Parámetros

page_size
integer

Amount of templates per page

page
integer

The page number

Respuestas
Tipo de contenido
application/json

OK

page_size
integer
Requerido
ejemplo1

How many items in page

page
integer
Requerido
ejemplo2

The current page number

total_pages
integer
Requerido
ejemplo10

Count of pages

total_items
integer
Requerido
ejemplo25

Total amount of all template fragments

_embedded
object
Requerido
template_fragments
array

List of Fragment Templates

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

ID for this template fragment

channel
string
ejemplosms
Debe ser uno de:smsvoice
locale
string
ejemploen-us

A Locale in IETF BCP 47 format

text
string
ejemploText 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
ejemplo2023-08-30T15:20:15.17865735Z
date_created
string(date-time)
ejemplo2021-08-30T20:12:15.17865735Z
_links
object
self
object
href
string(uri)
Requerido

Target URL

template
object
href
string(uri)
Requerido

Target URL

_links
object
Requerido
self
object
href
string(uri)
Requerido

Target URL

next
object
href
string(uri)
Requerido

Target URL

prev
object
href
string(uri)
Requerido

Target URL

first
object
href
string(uri)
Requerido

Target URL

last
object
href
string(uri)
Requerido

Target URL

Ejemplo Respuesta

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

Autenticación

Esta API admite tanto la autenticación JWT como la básica. La autenticación básica es más fácil para empezar, pero no admite funciones avanzadas como ACL.

Puede utilizar o bien la autenticación JWT o Basic, pero no ambas a la vez.

ClaveDescripciónDóndeEjemplo
Authorization

Su token web JSON.
Más información sobre los JWT

Headers

Bearer <JWT>
Authorization

Clave API codificada en Base64 y secreto unidos por dos puntos.
Seguir leyendo

Headers

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

Ruta Parámetros

template_id
string
Requerido

The template UUID

Cuerpo de la solicitud
Tipo de contenido
application/json

channel
string
Requerido
ejemplosms

The channel name

Debe ser uno de:smsvoice
locale
string
Requerido
ejemploen-us

The locale code, in lowercase

text
string
Requerido
ejemploThe 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}

Ejemplo Solicitar

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

Respuestas
Tipo de contenido
application/json

OK

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

ID for this template fragment

channel
string
ejemplosms
Debe ser uno de:smsvoice
locale
string
ejemploen-us

A Locale in IETF BCP 47 format

text
string
ejemploText 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
ejemplo2023-08-30T15:20:15.17865735Z
date_created
string(date-time)
ejemplo2021-08-30T20:12:15.17865735Z
_links
object
self
object
href
string(uri)
Requerido

Target URL

template
object
href
string(uri)
Requerido

Target URL

Ejemplo Respuesta

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

Autenticación

Esta API admite tanto la autenticación JWT como la básica. La autenticación básica es más fácil para empezar, pero no admite funciones avanzadas como ACL.

Puede utilizar o bien la autenticación JWT o Basic, pero no ambas a la vez.

ClaveDescripciónDóndeEjemplo
Authorization

Su token web JSON.
Más información sobre los JWT

Headers

Bearer <JWT>
Authorization

Clave API codificada en Base64 y secreto unidos por dos puntos.
Seguir leyendo

Headers

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

Ruta Parámetros

template_id
string
Requerido

The template UUID

template_fragment_id
string
Requerido

The template fragment UUID

Respuestas
Tipo de contenido
application/json

OK

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

ID for this template fragment

channel
string
ejemplosms
Debe ser uno de:smsvoice
locale
string
ejemploen-us

A Locale in IETF BCP 47 format

text
string
ejemploText 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
ejemplo2023-08-30T15:20:15.17865735Z
date_created
string(date-time)
ejemplo2021-08-30T20:12:15.17865735Z
_links
object
self
object
href
string(uri)
Requerido

Target URL

template
object
href
string(uri)
Requerido

Target URL

Ejemplo Respuesta

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

Autenticación

Esta API admite tanto la autenticación JWT como la básica. La autenticación básica es más fácil para empezar, pero no admite funciones avanzadas como ACL.

Puede utilizar o bien la autenticación JWT o Basic, pero no ambas a la vez.

ClaveDescripciónDóndeEjemplo
Authorization

Su token web JSON.
Más información sobre los JWT

Headers

Bearer <JWT>
Authorization

Clave API codificada en Base64 y secreto unidos por dos puntos.
Seguir leyendo

Headers

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

Ruta Parámetros

template_id
string
Requerido

The template UUID

template_fragment_id
string
Requerido

The template fragment UUID

Cuerpo de la solicitud
Tipo de contenido
application/json

text
string
Requerido
ejemploThe 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}

Ejemplo Solicitar

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

Respuestas
Tipo de contenido
application/json

OK

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

ID for this template fragment

channel
string
ejemplosms
Debe ser uno de:smsvoice
locale
string
ejemploen-us

A Locale in IETF BCP 47 format

text
string
ejemploText 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
ejemplo2023-08-30T15:20:15.17865735Z
date_created
string(date-time)
ejemplo2021-08-30T20:12:15.17865735Z
_links
object
self
object
href
string(uri)
Requerido

Target URL

template
object
href
string(uri)
Requerido

Target URL

Ejemplo Respuesta

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

Autenticación

Esta API admite tanto la autenticación JWT como la básica. La autenticación básica es más fácil para empezar, pero no admite funciones avanzadas como ACL.

Puede utilizar o bien la autenticación JWT o Basic, pero no ambas a la vez.

ClaveDescripciónDóndeEjemplo
Authorization

Su token web JSON.
Más información sobre los JWT

Headers

Bearer <JWT>
Authorization

Clave API codificada en Base64 y secreto unidos por dos puntos.
Seguir leyendo

Headers

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

Ruta Parámetros

template_id
string
Requerido

The template UUID

template_fragment_id
string
Requerido

The template fragment UUID

Respuestas

No Content

Webhooks

Los webhooks son una extensión de una API, pero en lugar de que tu código solicite datos, la API te los envía a ti. Los datos llegan en una petición web a tu aplicación.

Para obtener más información sobre los webhooks, consulte nuestra página documentación sobre webhooks.

Esta API puede enviar cualquiera de los webhooks documentados a continuación a la URL que haya configurado. Debe responder con una respuesta HTTP 200 o 204, o se volverán a intentar las solicitudes.

Operaciones disponibles

Events Callback webhook

An inbound events webhook.

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

Cuerpo de la solicitud
Tipo de contenido
application/json

request_id
string
Requerido
ejemploc11236f4-00bf-4b89-84ba-88b25df97315

The ID of the request

triggered_at
string(date-time)
Requerido
ejemplo2020-01-01T14:00:00.000Z

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

type
string
Requerido
ejemploevent

Type of response

channel
string
Requerido
ejemplosms

The channel

status
string
Requerido
ejemplocompleted

Current status of this request

Debe ser uno de:completedfaileduser_rejectedrejected
finalized_at
string(date-time)
Requerido
ejemplo2020-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
ejemplomy-personal-ref

Contains the client reference given in the original Verify request.

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

Request status update webhook

An inbound status update for a particular request.

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

Cuerpo de la solicitud
Tipo de contenido
application/json

request_id
string
Requerido
ejemploc11236f4-00bf-4b89-84ba-88b25df97315

The ID of the request

submitted_at
string(date-time)
Requerido
ejemplo2020-01-01T14:00:00.000Z

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

status
string
Requerido
ejemplocompleted

Current status of this request

Debe ser uno de:completedfailedexpired
type
string
Requerido
ejemplosummary

Type of response

channel_timeout
integer
Requerido
ejemplo300

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

workflow
array
Requerido
channel
string

The channel

Debe ser uno de: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
ejemplocompleted

Current status of this request

Debe ser uno de:unusedcompletedfailedexpireduser_rejected
client_ref
string
ejemplomy-personal-ref

Contains the client reference given in the original Verify request.

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

Silent Auth Request Update webhook

An inbound request update for an Asynchronous Silent Authentication workflow.

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

Cuerpo de la solicitud
Tipo de contenido
application/json

request_id
string
Requerido
ejemploc11236f4-00bf-4b89-84ba-88b25df97315

The ID of the request

triggered_at
string(date-time)
Requerido
ejemplo2020-01-01T14:00:00.000Z

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

type
string
Requerido
ejemploevent

Type of response

channel
string
Requerido
Debe ser uno de:silent_auth
status
string
Requerido
ejemploaction_pending

Current status of this request

Debe ser uno de:completedfaileduser_rejectedexpiredaction_pending
action
array
type
string

Description of workflow event

Debe ser uno de:check
check_url
string
ejemplohttps://api.nexmo.com/v2/verify/{request_id}/silent-auth/redirect

URL for Silent Auth Verify workflow completion

Ejemplo 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"
      }
   ]
}

Errores

La siguiente es una lista no exhaustiva de códigos de error que pueden producirse al utilizar esta API.

Estos códigos se suman a cualquiera de nuestros códigos de error genéricos.

CódigoInformación
fragment-exists

Descripción

A template fragment for this channel and locale already exists

Resolución

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

template-fragment-not-found

Descripción

Template Fragment not found

Resolución

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

template-not-found

Descripción

Template not found

Resolución

Check the ID of the template you are trying to access

template-exists

Descripción

A template with this name already exists

Resolución

Choose a different template name in the request

not-empty-template

Descripción

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

Resolución

Delete the individual template fragments, then try again

forbidden

Descripción

Templates management is not enabled for your account

Resolución

Contact Vonage support to enable custom template management

expired

Descripción

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

Resolución

Request a new Verification

no-code

Descripción

The current Verify workflow step does not support a code.

Resolución

Change to a valid workflow to handle your request

max-templates

Descripción

An account can only have a maximum of 10 custom templates

Resolución

Delete a template before retrying

concurrent

Descripción

Concurrent verifications to the same number are not allowed.

Resolución

In flight verification needs to expire, fail or be completed

invalid-code

Descripción

The code you provided does not match the expected value.

Resolución

Retry with the correct value or fail the request

no-events

Descripción

The code you provided does not match the expected value.

Resolución

Retry with the correct value or fail the request

request-not-found

Descripción

The request ID provided could not be found.

Resolución

Retry with a valid request ID

msisdn-error

Descripción

The device MSISDN does not match.

Resolución

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

precondition-failed

Descripción

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

Resolución

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

network-error

Descripción

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

Resolución

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