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.

Télécharger la spécification OpenAPI

Verify

Provides 2FA authentication for end-users.

Opérations disponibles

Request a verification be sent to a user

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

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

Authentification

Cette API prend en charge l'authentification JWT et l'authentification de base. L'authentification de base est plus facile à mettre en œuvre, mais elle ne prend pas en charge les fonctions avancées telles que les listes de contrôle d'accès.

Vous pouvez utiliser l'authentification JWT ou l'authentification de base, mais pas les deux en même temps.

CléDescriptionOùExemple
Authorization

Votre jeton web JSON.
En savoir plus sur les JWT

Headers

Bearer <JWT>
Authorization

Clé et secret de l'API encodés en Base64 et reliés par deux points.
En savoir plus

Headers

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

Corps de la demande
Type de contenu
application/json

locale
string
Défauten-us
exemplees-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
Défaut180
exemple180

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
exemplemyPersonalRef

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

code_length
integer
Défaut4
exemple4

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

Il doit s'agir de l'un d'entre eux :45678910
code
string
Min4
Max10
exemplee4dR1Qz

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
exempleACME

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

L'un des
channel
string
Exigée
exemplesilent_auth

The channel

Il doit s'agir de l'un d'entre eux :silent_auth
to
string
Exigée
Min1
Max50
exemple447700900000

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
exemplehttps://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
Défauttrue

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.

Exemple Demande

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

Réponses
Type de contenu
application/json

The request was started

request_id
string
Exigée
exemplec11236f4-00bf-4b89-84ba-88b25df97315

The ID of the request

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

Exemple Réponse

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

Authentification

Cette API prend en charge l'authentification JWT et l'authentification de base. L'authentification de base est plus facile à mettre en œuvre, mais elle ne prend pas en charge les fonctions avancées telles que les listes de contrôle d'accès.

Vous pouvez utiliser l'authentification JWT ou l'authentification de base, mais pas les deux en même temps.

CléDescriptionOùExemple
Authorization

Votre jeton web JSON.
En savoir plus sur les JWT

Headers

Bearer <JWT>
Authorization

Clé et secret de l'API encodés en Base64 et reliés par deux points.
En savoir plus

Headers

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

Trajectoire Paramètres

request_id
string
Exigée

ID of the verify request

Corps de la demande
Type de contenu
application/json

code
string
Exigée
Min4
Max10
exemple1234

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

Exemple Demande

{
   "code": "1234"
}

Réponses
Type de contenu
application/json

OK

request_id
string
exemple90596ac8-e1f1-46a9-a80f-ebd55e2296ae
status
string
exemplecompleted

Exemple Réponse

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

Authentification

Cette API prend en charge l'authentification JWT et l'authentification de base. L'authentification de base est plus facile à mettre en œuvre, mais elle ne prend pas en charge les fonctions avancées telles que les listes de contrôle d'accès.

Vous pouvez utiliser l'authentification JWT ou l'authentification de base, mais pas les deux en même temps.

CléDescriptionOùExemple
Authorization

Votre jeton web JSON.
En savoir plus sur les JWT

Headers

Bearer <JWT>
Authorization

Clé et secret de l'API encodés en Base64 et reliés par deux points.
En savoir plus

Headers

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

Trajectoire Paramètres

request_id
string
Exigée

ID of the verify request

Réponses

No content

Next workflow

Move the request onto the next workflow, if available.

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

Authentification

Cette API prend en charge l'authentification JWT et l'authentification de base. L'authentification de base est plus facile à mettre en œuvre, mais elle ne prend pas en charge les fonctions avancées telles que les listes de contrôle d'accès.

Vous pouvez utiliser l'authentification JWT ou l'authentification de base, mais pas les deux en même temps.

CléDescriptionOùExemple
Authorization

Votre jeton web JSON.
En savoir plus sur les JWT

Headers

Bearer <JWT>
Authorization

Clé et secret de l'API encodés en Base64 et reliés par deux points.
En savoir plus

Headers

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

Trajectoire Paramètres

request_id
string
Exigée

ID of the verify request

Réponses

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

Trajectoire Paramètres

request_id
string
Exigée

ID of the verify request

Réponses
Type de contenu
application/json

Carrier Success

request_id
string
exemplec11236f4-00bf-4b89-84ba-88b25df9731
code
string
exemplesi9sfG

Exemple Réponse

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

Templates

Create and modify custom templates in Verify

Opérations 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

Authentification

Cette API prend en charge l'authentification JWT et l'authentification de base. L'authentification de base est plus facile à mettre en œuvre, mais elle ne prend pas en charge les fonctions avancées telles que les listes de contrôle d'accès.

Vous pouvez utiliser l'authentification JWT ou l'authentification de base, mais pas les deux en même temps.

CléDescriptionOùExemple
Authorization

Votre jeton web JSON.
En savoir plus sur les JWT

Headers

Bearer <JWT>
Authorization

Clé et secret de l'API encodés en Base64 et reliés par deux points.
En savoir plus

Headers

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

Demande de renseignements Paramètres

page_size
integer

Amount of templates per page

page
integer

The page number

Réponses
Type de contenu
application/json

OK

page_size
integer
Exigée
exemple1

How many items in page

page
integer
Exigée
exemple2

The current page number

total_pages
integer
Exigée
exemple10

Count of pages

total_items
integer
Exigée
exemple25

Total amount of all templates

_embedded
object
Exigée
templates
array

List of templates

template_id
string(uuid)
Exigée
exemple8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9
name
string
Exigée
exemplemy-template
is_default
boolean
Exigée
exempletrue
_links
object
Exigée
self
object
href
string(uri)
Exigée

Target URL

fragments
object
href
string(uri)
Exigée

Target URL

_links
object
Exigée
self
object
href
string(uri)
Exigée

Target URL

next
object
href
string(uri)
Exigée

Target URL

prev
object
href
string(uri)
Exigée

Target URL

first
object
href
string(uri)
Exigée

Target URL

last
object
href
string(uri)
Exigée

Target URL

Exemple Réponse

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

Authentification

Cette API prend en charge l'authentification JWT et l'authentification de base. L'authentification de base est plus facile à mettre en œuvre, mais elle ne prend pas en charge les fonctions avancées telles que les listes de contrôle d'accès.

Vous pouvez utiliser l'authentification JWT ou l'authentification de base, mais pas les deux en même temps.

CléDescriptionOùExemple
Authorization

Votre jeton web JSON.
En savoir plus sur les JWT

Headers

Bearer <JWT>
Authorization

Clé et secret de l'API encodés en Base64 et reliés par deux points.
En savoir plus

Headers

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

Corps de la demande
Type de contenu
application/json

name
Exigée
Min1
Max64
exemplemy-template

Reference name for template.

Exemple Demande

{
   "name": "my-template"
}

Réponses
Type de contenu
application/json

OK

template_id
string(uuid)
Exigée
exemple8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9
name
string
Exigée
exemplemy-template
is_default
boolean
Exigée
exempletrue
_links
object
Exigée
self
object
href
string(uri)
Exigée

Target URL

fragments
object
href
string(uri)
Exigée

Target URL

Exemple Réponse

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

Authentification

Cette API prend en charge l'authentification JWT et l'authentification de base. L'authentification de base est plus facile à mettre en œuvre, mais elle ne prend pas en charge les fonctions avancées telles que les listes de contrôle d'accès.

Vous pouvez utiliser l'authentification JWT ou l'authentification de base, mais pas les deux en même temps.

CléDescriptionOùExemple
Authorization

Votre jeton web JSON.
En savoir plus sur les JWT

Headers

Bearer <JWT>
Authorization

Clé et secret de l'API encodés en Base64 et reliés par deux points.
En savoir plus

Headers

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

Trajectoire Paramètres

template_id
string
Exigée

The template UUID

Réponses
Type de contenu
application/json

OK

template_id
string(uuid)
Exigée
exemple8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9
name
string
Exigée
exemplemy-template
is_default
boolean
Exigée
exempletrue
_links
object
Exigée
self
object
href
string(uri)
Exigée

Target URL

fragments
object
href
string(uri)
Exigée

Target URL

Exemple Réponse

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

Authentification

Cette API prend en charge l'authentification JWT et l'authentification de base. L'authentification de base est plus facile à mettre en œuvre, mais elle ne prend pas en charge les fonctions avancées telles que les listes de contrôle d'accès.

Vous pouvez utiliser l'authentification JWT ou l'authentification de base, mais pas les deux en même temps.

CléDescriptionOùExemple
Authorization

Votre jeton web JSON.
En savoir plus sur les JWT

Headers

Bearer <JWT>
Authorization

Clé et secret de l'API encodés en Base64 et reliés par deux points.
En savoir plus

Headers

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

Trajectoire Paramètres

template_id
string
Exigée

The template UUID

Réponses

No Content

Update a template

Update a template

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

Authentification

Cette API prend en charge l'authentification JWT et l'authentification de base. L'authentification de base est plus facile à mettre en œuvre, mais elle ne prend pas en charge les fonctions avancées telles que les listes de contrôle d'accès.

Vous pouvez utiliser l'authentification JWT ou l'authentification de base, mais pas les deux en même temps.

CléDescriptionOùExemple
Authorization

Votre jeton web JSON.
En savoir plus sur les JWT

Headers

Bearer <JWT>
Authorization

Clé et secret de l'API encodés en Base64 et reliés par deux points.
En savoir plus

Headers

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

Trajectoire Paramètres

template_id
string
Exigée

The template UUID

Corps de la demande
Type de contenu
application/json

name
exemplemy-template

Reference name for template.

is_default
boolean
exempletrue

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

Exemple Demande

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

Réponses
Type de contenu
application/json

OK

template_id
string(uuid)
Exigée
exemple8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9
name
string
Exigée
exemplemy-template
is_default
boolean
Exigée
exempletrue
_links
object
Exigée
self
object
href
string(uri)
Exigée

Target URL

fragments
object
href
string(uri)
Exigée

Target URL

Exemple Réponse

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

Opérations disponibles

List template fragments

List template fragments

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

Authentification

Cette API prend en charge l'authentification JWT et l'authentification de base. L'authentification de base est plus facile à mettre en œuvre, mais elle ne prend pas en charge les fonctions avancées telles que les listes de contrôle d'accès.

Vous pouvez utiliser l'authentification JWT ou l'authentification de base, mais pas les deux en même temps.

CléDescriptionOùExemple
Authorization

Votre jeton web JSON.
En savoir plus sur les JWT

Headers

Bearer <JWT>
Authorization

Clé et secret de l'API encodés en Base64 et reliés par deux points.
En savoir plus

Headers

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

Trajectoire Paramètres

template_id
string
Exigée

The template UUID

Demande de renseignements Paramètres

page_size
integer

Amount of templates per page

page
integer

The page number

Réponses
Type de contenu
application/json

OK

page_size
integer
Exigée
exemple1

How many items in page

page
integer
Exigée
exemple2

The current page number

total_pages
integer
Exigée
exemple10

Count of pages

total_items
integer
Exigée
exemple25

Total amount of all template fragments

_embedded
object
Exigée
template_fragments
array

List of Fragment Templates

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

ID for this template fragment

channel
string
exemplesms
Il doit s'agir de l'un d'entre eux :smsvoice
locale
string
exempleen-us

A Locale in IETF BCP 47 format

text
string
exempleText 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
exemple2023-08-30T15:20:15.17865735Z
date_created
string(date-time)
exemple2021-08-30T20:12:15.17865735Z
_links
object
self
object
href
string(uri)
Exigée

Target URL

template
object
href
string(uri)
Exigée

Target URL

_links
object
Exigée
self
object
href
string(uri)
Exigée

Target URL

next
object
href
string(uri)
Exigée

Target URL

prev
object
href
string(uri)
Exigée

Target URL

first
object
href
string(uri)
Exigée

Target URL

last
object
href
string(uri)
Exigée

Target URL

Exemple Réponse

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

Authentification

Cette API prend en charge l'authentification JWT et l'authentification de base. L'authentification de base est plus facile à mettre en œuvre, mais elle ne prend pas en charge les fonctions avancées telles que les listes de contrôle d'accès.

Vous pouvez utiliser l'authentification JWT ou l'authentification de base, mais pas les deux en même temps.

CléDescriptionOùExemple
Authorization

Votre jeton web JSON.
En savoir plus sur les JWT

Headers

Bearer <JWT>
Authorization

Clé et secret de l'API encodés en Base64 et reliés par deux points.
En savoir plus

Headers

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

Trajectoire Paramètres

template_id
string
Exigée

The template UUID

Corps de la demande
Type de contenu
application/json

channel
string
Exigée
exemplesms

The channel name

Il doit s'agir de l'un d'entre eux :smsvoice
locale
string
Exigée
exempleen-us

The locale code, in lowercase

text
string
Exigée
exempleThe 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}

Exemple Demande

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

Réponses
Type de contenu
application/json

OK

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

ID for this template fragment

channel
string
exemplesms
Il doit s'agir de l'un d'entre eux :smsvoice
locale
string
exempleen-us

A Locale in IETF BCP 47 format

text
string
exempleText 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
exemple2023-08-30T15:20:15.17865735Z
date_created
string(date-time)
exemple2021-08-30T20:12:15.17865735Z
_links
object
self
object
href
string(uri)
Exigée

Target URL

template
object
href
string(uri)
Exigée

Target URL

Exemple Réponse

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

Authentification

Cette API prend en charge l'authentification JWT et l'authentification de base. L'authentification de base est plus facile à mettre en œuvre, mais elle ne prend pas en charge les fonctions avancées telles que les listes de contrôle d'accès.

Vous pouvez utiliser l'authentification JWT ou l'authentification de base, mais pas les deux en même temps.

CléDescriptionOùExemple
Authorization

Votre jeton web JSON.
En savoir plus sur les JWT

Headers

Bearer <JWT>
Authorization

Clé et secret de l'API encodés en Base64 et reliés par deux points.
En savoir plus

Headers

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

Trajectoire Paramètres

template_id
string
Exigée

The template UUID

template_fragment_id
string
Exigée

The template fragment UUID

Réponses
Type de contenu
application/json

OK

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

ID for this template fragment

channel
string
exemplesms
Il doit s'agir de l'un d'entre eux :smsvoice
locale
string
exempleen-us

A Locale in IETF BCP 47 format

text
string
exempleText 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
exemple2023-08-30T15:20:15.17865735Z
date_created
string(date-time)
exemple2021-08-30T20:12:15.17865735Z
_links
object
self
object
href
string(uri)
Exigée

Target URL

template
object
href
string(uri)
Exigée

Target URL

Exemple Réponse

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

Authentification

Cette API prend en charge l'authentification JWT et l'authentification de base. L'authentification de base est plus facile à mettre en œuvre, mais elle ne prend pas en charge les fonctions avancées telles que les listes de contrôle d'accès.

Vous pouvez utiliser l'authentification JWT ou l'authentification de base, mais pas les deux en même temps.

CléDescriptionOùExemple
Authorization

Votre jeton web JSON.
En savoir plus sur les JWT

Headers

Bearer <JWT>
Authorization

Clé et secret de l'API encodés en Base64 et reliés par deux points.
En savoir plus

Headers

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

Trajectoire Paramètres

template_id
string
Exigée

The template UUID

template_fragment_id
string
Exigée

The template fragment UUID

Corps de la demande
Type de contenu
application/json

text
string
Exigée
exempleThe 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}

Exemple Demande

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

Réponses
Type de contenu
application/json

OK

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

ID for this template fragment

channel
string
exemplesms
Il doit s'agir de l'un d'entre eux :smsvoice
locale
string
exempleen-us

A Locale in IETF BCP 47 format

text
string
exempleText 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
exemple2023-08-30T15:20:15.17865735Z
date_created
string(date-time)
exemple2021-08-30T20:12:15.17865735Z
_links
object
self
object
href
string(uri)
Exigée

Target URL

template
object
href
string(uri)
Exigée

Target URL

Exemple Réponse

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

Authentification

Cette API prend en charge l'authentification JWT et l'authentification de base. L'authentification de base est plus facile à mettre en œuvre, mais elle ne prend pas en charge les fonctions avancées telles que les listes de contrôle d'accès.

Vous pouvez utiliser l'authentification JWT ou l'authentification de base, mais pas les deux en même temps.

CléDescriptionOùExemple
Authorization

Votre jeton web JSON.
En savoir plus sur les JWT

Headers

Bearer <JWT>
Authorization

Clé et secret de l'API encodés en Base64 et reliés par deux points.
En savoir plus

Headers

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

Trajectoire Paramètres

template_id
string
Exigée

The template UUID

template_fragment_id
string
Exigée

The template fragment UUID

Réponses

No Content

Crochets Web

Les webhooks sont une extension d'une API, mais au lieu que votre code demande des données, l'API vous envoie des données. Les données arrivent dans une requête web à votre application.

Pour en savoir plus sur les webhooks, consultez notre site documentation sur les webhooks.

Cette API peut envoyer l'un des webhooks décrits ci-dessous à l'URL que vous avez configurée. Vous devez répondre avec une réponse HTTP 200 ou 204, sinon les demandes seront relancées.

Opérations disponibles

Events Callback webhook

An inbound events webhook.

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

Corps de la demande
Type de contenu
application/json

request_id
string
Exigée
exemplec11236f4-00bf-4b89-84ba-88b25df97315

The ID of the request

triggered_at
string(date-time)
Exigée
exemple2020-01-01T14:00:00.000Z

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

type
string
Exigée
exempleevent

Type of response

channel
string
Exigée
exemplesms

The channel

status
string
Exigée
exemplecompleted

Current status of this request

Il doit s'agir de l'un d'entre eux :completedfaileduser_rejectedrejected
finalized_at
string(date-time)
Exigée
exemple2020-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
exemplemy-personal-ref

Contains the client reference given in the original Verify request.

Exemple Charge utile

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

Corps de la demande
Type de contenu
application/json

request_id
string
Exigée
exemplec11236f4-00bf-4b89-84ba-88b25df97315

The ID of the request

submitted_at
string(date-time)
Exigée
exemple2020-01-01T14:00:00.000Z

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

status
string
Exigée
exemplecompleted

Current status of this request

Il doit s'agir de l'un d'entre eux :completedfailedexpired
type
string
Exigée
exemplesummary

Type of response

channel_timeout
integer
Exigée
exemple300

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

workflow
array
Exigée
channel
string

The channel

Il doit s'agir de l'un d'entre eux :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
exemplecompleted

Current status of this request

Il doit s'agir de l'un d'entre eux :unusedcompletedfailedexpireduser_rejected
client_ref
string
exemplemy-personal-ref

Contains the client reference given in the original Verify request.

Exemple Charge utile

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

Corps de la demande
Type de contenu
application/json

request_id
string
Exigée
exemplec11236f4-00bf-4b89-84ba-88b25df97315

The ID of the request

triggered_at
string(date-time)
Exigée
exemple2020-01-01T14:00:00.000Z

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

type
string
Exigée
exempleevent

Type of response

channel
string
Exigée
Il doit s'agir de l'un d'entre eux :silent_auth
status
string
Exigée
exempleaction_pending

Current status of this request

Il doit s'agir de l'un d'entre eux :completedfaileduser_rejectedexpiredaction_pending
action
array
type
string

Description of workflow event

Il doit s'agir de l'un d'entre eux :check
check_url
string
exemplehttps://api.nexmo.com/v2/verify/{request_id}/silent-auth/redirect

URL for Silent Auth Verify workflow completion

Exemple Charge utile

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

Erreurs

Voici une liste non exhaustive des codes d'erreur susceptibles de se produire lors de l'utilisation de cette API.

Ces codes s'ajoutent à ceux de notre site codes d'erreur génériques.

CodeInformations
fragment-exists

Description

A template fragment for this channel and locale already exists

Résolution

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

template-fragment-not-found

Description

Template Fragment not found

Résolution

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

template-not-found

Description

Template not found

Résolution

Check the ID of the template you are trying to access

template-exists

Description

A template with this name already exists

Résolution

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

Résolution

Delete the individual template fragments, then try again

forbidden

Description

Templates management is not enabled for your account

Résolution

Contact Vonage support to enable custom template management

expired

Description

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

Résolution

Request a new Verification

no-code

Description

The current Verify workflow step does not support a code.

Résolution

Change to a valid workflow to handle your request

max-templates

Description

An account can only have a maximum of 10 custom templates

Résolution

Delete a template before retrying

concurrent

Description

Concurrent verifications to the same number are not allowed.

Résolution

In flight verification needs to expire, fail or be completed

invalid-code

Description

The code you provided does not match the expected value.

Résolution

Retry with the correct value or fail the request

no-events

Description

The code you provided does not match the expected value.

Résolution

Retry with the correct value or fail the request

request-not-found

Description

The request ID provided could not be found.

Résolution

Retry with a valid request ID

msisdn-error

Description

The device MSISDN does not match.

Résolution

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.

Résolution

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.

Résolution

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