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.

OpenAPI-Spezifikation herunterladen

Verify

Provides 2FA authentication for end-users.

Verfügbare Operationen

Request a verification be sent to a user

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

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

Authentifizierung

Diese API unterstützt sowohl die JWT- als auch die Basis-Authentifizierung. Die Basisauthentifizierung ist einfacher zu handhaben, unterstützt aber keine erweiterten Funktionen wie ACLs.

Sie können entweder JWT oder Basic Authentication verwenden, aber nicht beides gleichzeitig.

Schlüssel	Beschreibung	Wo	Beispiel
Authorization	Ihr JSON-Web-Token. Lesen Sie mehr über JWTs	Headers	`Bearer <JWT>`
Authorization	Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt. Mehr lesen	Headers	`Basic <base64>`
	HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Anfrage Körper
Inhalt Typ
application/json

locale

string

Standarden-us

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

Standard180

Beispiel180

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

BeispielmyPersonalRef

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

code_length

integer

Standard4

Beispiel4

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

Muss eines der folgenden sein:45678910

code

string

Min4

Max10

Beispiele4dR1Qz

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

BeispielACME

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

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

Einer der

channel

string

Erforderlich

Beispielsilent_auth

The channel

Muss eines der folgenden sein:silent_auth

string

Erforderlich

Min1

Max50

Beispiel447700900000

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

Beispielhttps://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

Standardtrue

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.

Beispiel Anfrage

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

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

Antworten
Inhalt Typ
application/json

The request was started

request_id

string

Erforderlich

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

The ID of the request

check_url

string

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

Beispiel Antwort

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

Authentifizierung

Diese API unterstützt sowohl die JWT- als auch die Basis-Authentifizierung. Die Basisauthentifizierung ist einfacher zu handhaben, unterstützt aber keine erweiterten Funktionen wie ACLs.

Sie können entweder JWT oder Basic Authentication verwenden, aber nicht beides gleichzeitig.

Schlüssel	Beschreibung	Wo	Beispiel
Authorization	Ihr JSON-Web-Token. Lesen Sie mehr über JWTs	Headers	`Bearer <JWT>`
Authorization	Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt. Mehr lesen	Headers	`Basic <base64>`
	HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Pfad Parameter

request_id

string

Erforderlich

ID of the verify request

Anfrage Körper
Inhalt Typ
application/json

code

string

Erforderlich

Min4

Max10

Beispiel1234

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

Beispiel Anfrage

{
   "code": "1234"
}

{
   "code": "1234"
}

Antworten
Inhalt Typ
application/json

request_id

string

Beispiel90596ac8-e1f1-46a9-a80f-ebd55e2296ae

status

string

Beispielcompleted

Beispiel Antwort

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

Authentifizierung

Diese API unterstützt sowohl die JWT- als auch die Basis-Authentifizierung. Die Basisauthentifizierung ist einfacher zu handhaben, unterstützt aber keine erweiterten Funktionen wie ACLs.

Sie können entweder JWT oder Basic Authentication verwenden, aber nicht beides gleichzeitig.

Schlüssel	Beschreibung	Wo	Beispiel
Authorization	Ihr JSON-Web-Token. Lesen Sie mehr über JWTs	Headers	`Bearer <JWT>`
Authorization	Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt. Mehr lesen	Headers	`Basic <base64>`
	HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Pfad Parameter

request_id

string

Erforderlich

ID of the verify request

Antworten

No content

Next workflow

Move the request onto the next workflow, if available.

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

Authentifizierung

Diese API unterstützt sowohl die JWT- als auch die Basis-Authentifizierung. Die Basisauthentifizierung ist einfacher zu handhaben, unterstützt aber keine erweiterten Funktionen wie ACLs.

Sie können entweder JWT oder Basic Authentication verwenden, aber nicht beides gleichzeitig.

Schlüssel	Beschreibung	Wo	Beispiel
Authorization	Ihr JSON-Web-Token. Lesen Sie mehr über JWTs	Headers	`Bearer <JWT>`
Authorization	Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt. Mehr lesen	Headers	`Basic <base64>`
	HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Pfad Parameter

request_id

string

Erforderlich

ID of the verify request

Antworten

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

Pfad Parameter

request_id

string

Erforderlich

ID of the verify request

Antworten
Inhalt Typ
application/json

Carrier Success

request_id

string

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

code

string

Beispielsi9sfG

Beispiel Antwort

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

Templates

Create and modify custom templates in Verify

Verfügbare Operationen

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

Authentifizierung

Diese API unterstützt sowohl die JWT- als auch die Basis-Authentifizierung. Die Basisauthentifizierung ist einfacher zu handhaben, unterstützt aber keine erweiterten Funktionen wie ACLs.

Sie können entweder JWT oder Basic Authentication verwenden, aber nicht beides gleichzeitig.

Schlüssel	Beschreibung	Wo	Beispiel
Authorization	Ihr JSON-Web-Token. Lesen Sie mehr über JWTs	Headers	`Bearer <JWT>`
Authorization	Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt. Mehr lesen	Headers	`Basic <base64>`
	HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Abfrage Parameter

page_size

integer

Amount of templates per page

page

integer

The page number

Antworten
Inhalt Typ
application/json

page_size

integer

Erforderlich

Beispiel1

How many items in page

page

integer

Erforderlich

Beispiel2

The current page number

total_pages

integer

Erforderlich

Beispiel10

Count of pages

total_items

integer

Erforderlich

Beispiel25

Total amount of all templates

_embedded

object

Erforderlich

templates

array

List of templates

template_id

string(uuid)

Erforderlich

Beispiel8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9

name

string

Erforderlich

Beispielmy-template

is_default

boolean

Erforderlich

Beispieltrue

_links

object

Erforderlich

self

object

href

string(uri)

Erforderlich

Target URL

fragments

object

href

string(uri)

Erforderlich

Target URL

_links

object

Erforderlich

self

object

href

string(uri)

Erforderlich

Target URL

object

href

string(uri)

Erforderlich

Target URL

object

href

string(uri)

Erforderlich

Target URL

first

object

href

string(uri)

Erforderlich

Target URL

last

object

href

string(uri)

Erforderlich

Target URL

Beispiel Antwort

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

Authentifizierung

Diese API unterstützt sowohl die JWT- als auch die Basis-Authentifizierung. Die Basisauthentifizierung ist einfacher zu handhaben, unterstützt aber keine erweiterten Funktionen wie ACLs.

Sie können entweder JWT oder Basic Authentication verwenden, aber nicht beides gleichzeitig.

Schlüssel	Beschreibung	Wo	Beispiel
Authorization	Ihr JSON-Web-Token. Lesen Sie mehr über JWTs	Headers	`Bearer <JWT>`
Authorization	Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt. Mehr lesen	Headers	`Basic <base64>`
	HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Anfrage Körper
Inhalt Typ
application/json

name

Erforderlich

Min1

Max64

Beispielmy-template

Reference name for template.

Beispiel Anfrage

{
   "name": "my-template"
}

{
   "name": "my-template"
}

Antworten
Inhalt Typ
application/json

template_id

string(uuid)

Erforderlich

Beispiel8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9

name

string

Erforderlich

Beispielmy-template

is_default

boolean

Erforderlich

Beispieltrue

_links

object

Erforderlich

self

object

href

string(uri)

Erforderlich

Target URL

fragments

object

href

string(uri)

Erforderlich

Target URL

Beispiel Antwort

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

Authentifizierung

Diese API unterstützt sowohl die JWT- als auch die Basis-Authentifizierung. Die Basisauthentifizierung ist einfacher zu handhaben, unterstützt aber keine erweiterten Funktionen wie ACLs.

Sie können entweder JWT oder Basic Authentication verwenden, aber nicht beides gleichzeitig.

Schlüssel	Beschreibung	Wo	Beispiel
Authorization	Ihr JSON-Web-Token. Lesen Sie mehr über JWTs	Headers	`Bearer <JWT>`
Authorization	Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt. Mehr lesen	Headers	`Basic <base64>`
	HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Pfad Parameter

template_id

string

Erforderlich

The template UUID

Antworten
Inhalt Typ
application/json

template_id

string(uuid)

Erforderlich

Beispiel8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9

name

string

Erforderlich

Beispielmy-template

is_default

boolean

Erforderlich

Beispieltrue

_links

object

Erforderlich

self

object

href

string(uri)

Erforderlich

Target URL

fragments

object

href

string(uri)

Erforderlich

Target URL

Beispiel Antwort

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

Authentifizierung

Diese API unterstützt sowohl die JWT- als auch die Basis-Authentifizierung. Die Basisauthentifizierung ist einfacher zu handhaben, unterstützt aber keine erweiterten Funktionen wie ACLs.

Sie können entweder JWT oder Basic Authentication verwenden, aber nicht beides gleichzeitig.

Schlüssel	Beschreibung	Wo	Beispiel
Authorization	Ihr JSON-Web-Token. Lesen Sie mehr über JWTs	Headers	`Bearer <JWT>`
Authorization	Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt. Mehr lesen	Headers	`Basic <base64>`
	HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Pfad Parameter

template_id

string

Erforderlich

The template UUID

Antworten

No Content

Update a template

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

Authentifizierung

Diese API unterstützt sowohl die JWT- als auch die Basis-Authentifizierung. Die Basisauthentifizierung ist einfacher zu handhaben, unterstützt aber keine erweiterten Funktionen wie ACLs.

Sie können entweder JWT oder Basic Authentication verwenden, aber nicht beides gleichzeitig.

Schlüssel	Beschreibung	Wo	Beispiel
Authorization	Ihr JSON-Web-Token. Lesen Sie mehr über JWTs	Headers	`Bearer <JWT>`
Authorization	Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt. Mehr lesen	Headers	`Basic <base64>`
	HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Pfad Parameter

template_id

string

Erforderlich

The template UUID

Anfrage Körper
Inhalt Typ
application/json

name

Beispielmy-template

Reference name for template.

is_default

boolean

Beispieltrue

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

Beispiel Anfrage

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

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

Antworten
Inhalt Typ
application/json

template_id

string(uuid)

Erforderlich

Beispiel8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9

name

string

Erforderlich

Beispielmy-template

is_default

boolean

Erforderlich

Beispieltrue

_links

object

Erforderlich

self

object

href

string(uri)

Erforderlich

Target URL

fragments

object

href

string(uri)

Erforderlich

Target URL

Beispiel Antwort

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

Verfügbare Operationen

List template fragments

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

Authentifizierung

Diese API unterstützt sowohl die JWT- als auch die Basis-Authentifizierung. Die Basisauthentifizierung ist einfacher zu handhaben, unterstützt aber keine erweiterten Funktionen wie ACLs.

Sie können entweder JWT oder Basic Authentication verwenden, aber nicht beides gleichzeitig.

Schlüssel	Beschreibung	Wo	Beispiel
Authorization	Ihr JSON-Web-Token. Lesen Sie mehr über JWTs	Headers	`Bearer <JWT>`
Authorization	Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt. Mehr lesen	Headers	`Basic <base64>`
	HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Pfad Parameter

template_id

string

Erforderlich

The template UUID

Abfrage Parameter

page_size

integer

Amount of templates per page

page

integer

The page number

Antworten
Inhalt Typ
application/json

page_size

integer

Erforderlich

Beispiel1

How many items in page

page

integer

Erforderlich

Beispiel2

The current page number

total_pages

integer

Erforderlich

Beispiel10

Count of pages

total_items

integer

Erforderlich

Beispiel25

Total amount of all template fragments

_embedded

object

Erforderlich

template_fragments

array

List of Fragment Templates

template_fragment_id

string

Beispielc70f446e-997a-4313-a081-60a02a31dc19

ID for this template fragment

channel

string

Beispielsms

Muss eines der folgenden sein:smsvoice

locale

string

Beispielen-us

A Locale in IETF BCP 47 format

text

string

Beispiel

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

Beispiel2023-08-30T15:20:15.17865735Z

date_created

string(date-time)

Beispiel2021-08-30T20:12:15.17865735Z

_links

object

self

object

href

string(uri)

Erforderlich

Target URL

template

object

href

string(uri)

Erforderlich

Target URL

_links

object

Erforderlich

self

object

href

string(uri)

Erforderlich

Target URL

object

href

string(uri)

Erforderlich

Target URL

object

href

string(uri)

Erforderlich

Target URL

first

object

href

string(uri)

Erforderlich

Target URL

last

object

href

string(uri)

Erforderlich

Target URL

Beispiel Antwort

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

Authentifizierung

Diese API unterstützt sowohl die JWT- als auch die Basis-Authentifizierung. Die Basisauthentifizierung ist einfacher zu handhaben, unterstützt aber keine erweiterten Funktionen wie ACLs.

Sie können entweder JWT oder Basic Authentication verwenden, aber nicht beides gleichzeitig.

Schlüssel	Beschreibung	Wo	Beispiel
Authorization	Ihr JSON-Web-Token. Lesen Sie mehr über JWTs	Headers	`Bearer <JWT>`
Authorization	Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt. Mehr lesen	Headers	`Basic <base64>`
	HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Pfad Parameter

template_id

string

Erforderlich

The template UUID

Anfrage Körper
Inhalt Typ
application/json

channel

string

Erforderlich

Beispielsms

The channel name

Muss eines der folgenden sein:smsvoice

locale

string

Erforderlich

Beispielen-us

The locale code, in lowercase

text

string

Erforderlich

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

Beispiel Anfrage

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

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

Antworten
Inhalt Typ
application/json

template_fragment_id

string

Beispielc70f446e-997a-4313-a081-60a02a31dc19

ID for this template fragment

channel

string

Beispielsms

Muss eines der folgenden sein:smsvoice

locale

string

Beispielen-us

A Locale in IETF BCP 47 format

text

string

Beispiel

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

Beispiel2023-08-30T15:20:15.17865735Z

date_created

string(date-time)

Beispiel2021-08-30T20:12:15.17865735Z

_links

object

self

object

href

string(uri)

Erforderlich

Target URL

template

object

href

string(uri)

Erforderlich

Target URL

Beispiel Antwort

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

Authentifizierung

Diese API unterstützt sowohl die JWT- als auch die Basis-Authentifizierung. Die Basisauthentifizierung ist einfacher zu handhaben, unterstützt aber keine erweiterten Funktionen wie ACLs.

Sie können entweder JWT oder Basic Authentication verwenden, aber nicht beides gleichzeitig.

Schlüssel	Beschreibung	Wo	Beispiel
Authorization	Ihr JSON-Web-Token. Lesen Sie mehr über JWTs	Headers	`Bearer <JWT>`
Authorization	Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt. Mehr lesen	Headers	`Basic <base64>`
	HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Pfad Parameter

template_id

string

Erforderlich

The template UUID

template_fragment_id

string

Erforderlich

The template fragment UUID

Antworten
Inhalt Typ
application/json

template_fragment_id

string

Beispielc70f446e-997a-4313-a081-60a02a31dc19

ID for this template fragment

channel

string

Beispielsms

Muss eines der folgenden sein:smsvoice

locale

string

Beispielen-us

A Locale in IETF BCP 47 format

text

string

Beispiel

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

Beispiel2023-08-30T15:20:15.17865735Z

date_created

string(date-time)

Beispiel2021-08-30T20:12:15.17865735Z

_links

object

self

object

href

string(uri)

Erforderlich

Target URL

template

object

href

string(uri)

Erforderlich

Target URL

Beispiel Antwort

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

Authentifizierung

Diese API unterstützt sowohl die JWT- als auch die Basis-Authentifizierung. Die Basisauthentifizierung ist einfacher zu handhaben, unterstützt aber keine erweiterten Funktionen wie ACLs.

Sie können entweder JWT oder Basic Authentication verwenden, aber nicht beides gleichzeitig.

Schlüssel	Beschreibung	Wo	Beispiel
Authorization	Ihr JSON-Web-Token. Lesen Sie mehr über JWTs	Headers	`Bearer <JWT>`
Authorization	Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt. Mehr lesen	Headers	`Basic <base64>`
	HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Pfad Parameter

template_id

string

Erforderlich

The template UUID

template_fragment_id

string

Erforderlich

The template fragment UUID

Anfrage Körper
Inhalt Typ
application/json

text

string

Erforderlich

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

Beispiel Anfrage

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

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

Antworten
Inhalt Typ
application/json

template_fragment_id

string

Beispielc70f446e-997a-4313-a081-60a02a31dc19

ID for this template fragment

channel

string

Beispielsms

Muss eines der folgenden sein:smsvoice

locale

string

Beispielen-us

A Locale in IETF BCP 47 format

text

string

Beispiel

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

Beispiel2023-08-30T15:20:15.17865735Z

date_created

string(date-time)

Beispiel2021-08-30T20:12:15.17865735Z

_links

object

self

object

href

string(uri)

Erforderlich

Target URL

template

object

href

string(uri)

Erforderlich

Target URL

Beispiel Antwort

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

Authentifizierung

Diese API unterstützt sowohl die JWT- als auch die Basis-Authentifizierung. Die Basisauthentifizierung ist einfacher zu handhaben, unterstützt aber keine erweiterten Funktionen wie ACLs.

Sie können entweder JWT oder Basic Authentication verwenden, aber nicht beides gleichzeitig.

Schlüssel	Beschreibung	Wo	Beispiel
Authorization	Ihr JSON-Web-Token. Lesen Sie mehr über JWTs	Headers	`Bearer <JWT>`
Authorization	Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt. Mehr lesen	Headers	`Basic <base64>`
	HTTP auth can be used for synchronous calls, for asynchronous calls and call backs use JWT authentication

Pfad Parameter

template_id

string

Erforderlich

The template UUID

template_fragment_id

string

Erforderlich

The template fragment UUID

Antworten

No Content

Webhaken

Webhooks sind eine Erweiterung einer API, aber anstatt dass Ihr Code Daten anfordert, sendet die API Daten an Sie. Die Daten werden in einer Webanforderung an Ihre Anwendung gesendet.

Um mehr über Webhooks zu erfahren, besuchen Sie unsere Website Webhooks-Dokumentation.

Diese API kann jeden der unten dokumentierten Webhooks an die von Ihnen konfigurierte URL senden. Sie müssen mit einer 200 oder 204 HTTP-Antwort antworten, andernfalls werden die Anfragen erneut versucht.

Verfügbare Operationen

Events Callback webhook

An inbound events webhook.

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

Anfrage Körper
Inhalt Typ
application/json

request_id

string

Erforderlich

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

The ID of the request

triggered_at

string(date-time)

Erforderlich

Beispiel2020-01-01T14:00:00.000Z

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

type

string

Erforderlich

Beispielevent

Type of response

channel

string

Erforderlich

Beispielsms

The channel

status

string

Erforderlich

Beispielcompleted

Current status of this request

Muss eines der folgenden sein:completedfaileduser_rejectedrejected

finalized_at

string(date-time)

Erforderlich

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

Beispielmy-personal-ref

Contains the client reference given in the original Verify request.

Beispiel Nutzlast

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

Anfrage Körper
Inhalt Typ
application/json

request_id

string

Erforderlich

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

The ID of the request

submitted_at

string(date-time)

Erforderlich

Beispiel2020-01-01T14:00:00.000Z

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

status

string

Erforderlich

Beispielcompleted

Current status of this request

Muss eines der folgenden sein:completedfailedexpired

type

string

Erforderlich

Beispielsummary

Type of response

channel_timeout

integer

Erforderlich

Beispiel300

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

workflow

array

Erforderlich

channel

string

The channel

Muss eines der folgenden sein: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

Beispielcompleted

Current status of this request

Muss eines der folgenden sein:unusedcompletedfailedexpireduser_rejected

client_ref

string

Beispielmy-personal-ref

Contains the client reference given in the original Verify request.

Beispiel Nutzlast

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

Anfrage Körper
Inhalt Typ
application/json

request_id

string

Erforderlich

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

The ID of the request

triggered_at

string(date-time)

Erforderlich

Beispiel2020-01-01T14:00:00.000Z

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

type

string

Erforderlich

Beispielevent

Type of response

channel

string

Erforderlich

Muss eines der folgenden sein:silent_auth

status

string

Erforderlich

Beispielaction_pending

Current status of this request

Muss eines der folgenden sein:completedfaileduser_rejectedexpiredaction_pending

action

array

type

string

Description of workflow event

Muss eines der folgenden sein:check

check_url

string

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

URL for Silent Auth Verify workflow completion

Beispiel Nutzlast

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

Fehler

Im Folgenden finden Sie eine nicht erschöpfende Liste von Fehlercodes, die bei der Verwendung dieser API auftreten können.

Diese Codes gelten zusätzlich zu unseren generische Fehlercodes.

Code	Informationen
fragment-exists	Beschreibung A template fragment for this channel and locale already exists Auflösung Change either the locale or channel to a combination not being used
template-fragment-not-found	Beschreibung Template Fragment not found Auflösung Check the ID of the template fragment you are trying to access
template-not-found	Beschreibung Template not found Auflösung Check the ID of the template you are trying to access
template-exists	Beschreibung A template with this name already exists Auflösung Choose a different template name in the request
not-empty-template	Beschreibung The template is not empty and cannot be deleted. Please delete its fragments first Auflösung Delete the individual template fragments, then try again
forbidden	Beschreibung Templates management is not enabled for your account Auflösung Contact Vonage support to enable custom template management
expired	Beschreibung An incorrect code has been provided too many times. Workflow terminated. Auflösung Request a new Verification
no-code	Beschreibung The current Verify workflow step does not support a code. Auflösung Change to a valid workflow to handle your request
max-templates	Beschreibung An account can only have a maximum of 10 custom templates Auflösung Delete a template before retrying
concurrent	Beschreibung Concurrent verifications to the same number are not allowed. Auflösung In flight verification needs to expire, fail or be completed
invalid-code	Beschreibung The code you provided does not match the expected value. Auflösung Retry with the correct value or fail the request
no-events	Beschreibung The code you provided does not match the expected value. Auflösung Retry with the correct value or fail the request
request-not-found	Beschreibung The request ID provided could not be found. Auflösung Retry with a valid request ID
msisdn-error	Beschreibung The device MSISDN does not match. Auflösung Silent Auth will not work with this device, try a different one.
precondition-failed	Beschreibung Conditions for the Silent Auth request to complete have not been met. Auflösung Silent Auth will not work with this device, try a different one.
network-error	Beschreibung The Silent Auth request could not be completed due to formatting or the carrier is not supported. Auflösung 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

Verfügbare Operationen

Request a verification be sent to a user

Authentifizierung

Anfrage Körper Inhalt Typapplication/json

Beispiel Anfrage

Antworten Inhalt Typapplication/json

Beispiel Antwort

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

Authentifizierung

Pfad Parameter

Anfrage Körper Inhalt Typapplication/json

Beispiel Anfrage

Antworten Inhalt Typapplication/json

Beispiel Antwort

Cancel a verification.

Authentifizierung

Pfad Parameter

Antworten

Next workflow

Authentifizierung

Pfad Parameter

Antworten

Attempt Silent Authentication completion

Pfad Parameter

Antworten Inhalt Typapplication/json

Beispiel Antwort

Templates

Verfügbare Operationen

List all templates

Authentifizierung

Abfrage Parameter

Antworten Inhalt Typapplication/json

Beispiel Antwort

Create a new template

Authentifizierung

Anfrage Körper Inhalt Typapplication/json

Beispiel Anfrage

Antworten Inhalt Typapplication/json

Beispiel Antwort

Get a template

Authentifizierung

Pfad Parameter

Antworten Inhalt Typapplication/json

Beispiel Antwort

Delete a template

Authentifizierung

Pfad Parameter

Antworten

Update a template

Authentifizierung

Pfad Parameter

Anfrage Körper Inhalt Typapplication/json

Beispiel Anfrage

Antworten Inhalt Typapplication/json

Beispiel Antwort

Template Fragments

Verfügbare Operationen

List template fragments

Authentifizierung

Pfad Parameter

Abfrage Parameter

Antworten Inhalt Typapplication/json

Beispiel Antwort

Create a template fragment

Authentifizierung

Pfad Parameter

Anfrage Körper Inhalt Typapplication/json

Beispiel Anfrage

Antworten Inhalt Typapplication/json

Beispiel Antwort

Get a template fragment

Authentifizierung

Pfad Parameter

Antworten Inhalt Typapplication/json

Beispiel Antwort

Update a template fragment

Authentifizierung

Pfad Parameter

Anfrage Körper
Inhalt Typ
application/json

Antworten
Inhalt Typ
application/json

Anfrage Körper
Inhalt Typ
application/json

Antworten
Inhalt Typ
application/json

Antworten
Inhalt Typ
application/json

Antworten
Inhalt Typ
application/json

Anfrage Körper
Inhalt Typ
application/json

Antworten
Inhalt Typ
application/json

Antworten
Inhalt Typ
application/json

Anfrage Körper
Inhalt Typ
application/json

Antworten
Inhalt Typ
application/json

Antworten
Inhalt Typ
application/json

Anfrage Körper
Inhalt Typ
application/json

Antworten
Inhalt Typ
application/json

Antworten
Inhalt Typ
application/json

Anfrage Körper
Inhalt Typ
application/json

Antworten
Inhalt Typ
application/json

Anfrage Körper
Inhalt Typ
application/json

Anfrage Körper
Inhalt Typ
application/json

Anfrage Körper
Inhalt Typ
application/json