{ "openapi": "3.0.3", "servers": [ { "url": "https://api.nexmo.com/verify" } ], "info": { "title": "Verify API (v1)", "x-metaTitle": "Vonage Verify v1.0 API Reference | Vonage API Documentation", "x-metaDescription": "Find quick answers to questions about the Vonage Verify API (v1.0) in this reference guide. Learn more in Vonage's API documentation.", "x-label": "Deprecated", "version": "1.2.4", "description": "The Verify API helps you to implement 2FA (two-factor authentication) in your applications. This is useful for:\n\n* Protecting against spam, by preventing spammers from creating multiple accounts\n* Monitoring suspicious activity, by forcing an account user to verify ownership of a number\n* Ensuring that you can reach your users at any time because you have their correct phone number\nMore information is available at ", "contact": { "name": "Vonage DevRel", "email": "devrel@vonage.com", "url": "https://developer.nexmo.com/" }, "termsOfService": "https://www.nexmo.com/terms-of-use", "license": { "name": "The MIT License (MIT)", "url": "https://opensource.org/licenses/MIT" } }, "externalDocs": { "description": "More information on the Verify product on our Developer Portal", "url": "https://developer.nexmo.com/verify/overview" }, "tags": [ { "name": "Verify Requests", "description": "Verify Requests" }, { "name": "Verify Check", "description": "Verify Check" }, { "name": "Verify Search", "description": "Verify Search" }, { "name": "Verify Control", "description": "Verify Control" }, { "name": "Fraud Management", "description": "Fraud Management" } ], "security": [ { "basicAuth": [] } ], "paths": { "/{format}": { "post": { "operationId": "verifyRequest", "tags": [ "Verify Requests" ], "summary": "Request a Verification", "description": "Use Verify request to generate and send a PIN to your user:\n\n1. Create a request to send a verification code to your user.\n\n2. Check the `status` field in the response to ensure that your request was successful (zero is success).\n\n3. Use the `request_id` field in the response for the Verify check.\n\n*Note that this endpoint is available by `GET` request as well as `POST`.*", "parameters": [ { "$ref": "#/components/parameters/format" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/verifyRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "examples": { "success": { "summary": "Request was started", "value": { "request_id": "abcdef0123456789abcdef0123456789", "status": "0" } }, "throttled": { "summary": "Request limit exceeded", "value": { "status": "1", "error_text": "Throttled" } }, "missing-param": { "summary": "Missing a parameter", "value": { "status": "2", "error_text": "Missing brand" } }, "invalid-param": { "summary": "Invalid parameter", "value": { "status": "3", "error_text": "Invalid value for number" } }, "invalid-creds": { "summary": "Invalid credentials", "value": { "status": "4", "error_text": "Invalid credentials were provided" } }, "internal-error": { "summary": "Internal Error", "value": { "status": "5", "error_text": "Internal Error" } }, "cannot-process": { "summary": "Unable to process message", "value": { "status": "6", "error_text": "The Vonage platform was unable to process this message for the following reason: The request could not be routed." } }, "blacklist": { "summary": "Blacklisted number", "value": { "status": "7", "error_text": "The number you are trying to verify is blacklisted for verification." } }, "account-disabled": { "summary": "Account is barred", "value": { "status": "8", "error_text": "The api_key you supplied is for an account that has been barred from submitting messages." } }, "quota-exceeded": { "summary": "Quota exceeded", "value": { "status": "9", "error_text": "Partner quota exceeded" } }, "concurrent": { "summary": "Concurrent verifications", "value": { "request_id": "abcdef0123456789abcdef0123456789", "status": "10", "error_text": "Concurrent verifications to the same number are not allowed" } }, "rejected": { "summary": "Rejected", "value": { "status": "15", "error_text": "The destination number is not in a supported network" } }, "not-permitted": { "summary": "Non-Permitted Destination", "value": { "status": "29", "error_text": "Your Vonage account is still in demo mode. While in demo mode you must add target numbers to the approved list for your account. Add funds to your account to remove this limitation." } } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/requestResponse" }, { "$ref": "#/components/schemas/requestErrorResponse" } ] } }, "text/xml": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/requestResponse" }, { "$ref": "#/components/schemas/requestErrorResponse" } ] } } } } } } }, "/check/{format}": { "post": { "description": "Use Verify check to confirm that the PIN you received from your user matches the one sent by Vonage in your Verify request.\n\n1. Send the verification `code` that your user supplied, with the corresponding `request_id` from the Verify request.\n2. Check the `status` of the response to determine if the code the user supplied matches the one sent by Vonage.\n\n*Note that this endpoint is available by `GET` request as well as `POST`.*", "operationId": "verifyCheck", "tags": [ "Verify Check" ], "summary": "Verify Check", "parameters": [ { "$ref": "#/components/parameters/format" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/checkRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "examples": { "success": { "summary": "The supplied code is correct for this request. Verification successful.", "value": { "request_id": "abcdef0123456789abcdef0123456789", "event_id": "0A00000012345678", "status": "0", "price": "0.10000000", "currency": "EUR", "estimated_price_messages_sent": "0.03330000" } }, "throttled": { "summary": "Request limit exceeded", "value": { "status": "1", "error_text": "Throttled" } }, "missing-param": { "summary": "Missing a parameter", "value": { "status": "2", "error_text": "Missing request_id" } }, "invalid-param": { "summary": "Invalid parameter", "value": { "status": "3", "error_text": "Invalid value for param: request_id" } }, "invalid-creds": { "summary": "Invalid credentials", "value": { "status": "4", "error_text": "Bad credentials" } }, "internal-error": { "summary": "Internal Error", "value": { "status": "5", "error_text": "Internal Error" } }, "unknown-requestid": { "summary": "This request_id is unknown or inactive", "value": { "status": "6", "error_text": "The Vonage platform was unable to process this message for the following reason: Request 'abcdef0123456789abcdef0123456789' was not found or it has been verified already." } }, "incorrect-code": { "summary": "PIN code is incorrect", "value": { "status": "16", "error_text": "The code inserted does not match the expected value" } }, "too-many-fails": { "summary": "Too many incorrect codes", "value": { "status": "17", "error_text": "The wrong code was provided too many times. Request terminated" } } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/checkResponse" }, { "$ref": "#/components/schemas/checkErrorResponse" } ] } }, "text/xml": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/checkResponse" }, { "$ref": "#/components/schemas/checkErrorResponse" } ] } } } } } } }, "/search/{format}": { "get": { "description": "Use Verify search to check the status of past or current verification requests:\n\n1. Send a Verify search request containing the `request_id`s of the verification requests you are interested in.\n2. Use the `status` of each verification request in the `checks` array of the response object to determine the outcome.\n\n*Note that this endpoint is available by `POST` request as well as `GET`.*", "operationId": "verifySearch", "tags": [ "Verify Search" ], "summary": "Verify Search", "parameters": [ { "$ref": "#/components/parameters/format" }, { "name": "request_id", "required": true, "in": "query", "description": "The `request_id` you received in the Verify Request Response. Required if `request_ids` not provided.", "schema": { "type": "string" }, "example": "abcdef0123456789abcdef0123456789" }, { "name": "request_ids", "required": false, "in": "query", "description": "More than one `request_id`. Each `request_id` is a new parameter in the Verify Search request. Required if `request_id` not provided.", "schema": { "type": "array", "items": { "type": "string", "example": "abcdef0123456789abcdef0123456789" }, "maxItems": 10 }, "style": "form", "explode": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "examples": { "success": { "summary": "The request was found", "value": { "request_id": "abcdef0123456789abcdef0123456789", "account_id": "abcdef01", "number": "447700900000", "sender_id": "verify", "date_submitted": "2020-01-01 12:00:00", "date_finalized": "2020-01-01 12:00:00", "checks": [ { "date_received": "2020-01-01 12:00:00", "code": "1111", "status": "INVALID", "ip_address": "" }, { "date_received": "2020-01-01 12:02:00", "code": "1234", "status": "VALID", "ip_address": "" } ], "first_event_date": "2020-01-01 12:00:00", "last_event_date": "2020-01-01 12:00:00", "price": "0.1000000", "currency": "EUR", "status": "SUCCESS", "estimated_price_messages_sent": "0.06660000", "events": [ { "id": "0A00000012345678", "type": "sms" }, { "id": "0A00000012345679", "type": "sms" } ] } }, "throttled": { "summary": "Request limit exceeded", "value": { "status": "1", "error_text": "Throttled" } }, "missing-param": { "summary": "Missing a parameter", "value": { "status": "2", "error_text": "Missing request_id" } }, "invalid-param": { "summary": "Invalid parameter", "value": { "status": "3", "error_text": "Invalid value for param: request_id" } }, "invalid-creds": { "summary": "Invalid credentials", "value": { "status": "4", "error_text": "Bad credentials" } }, "internal-error": { "summary": "Internal Error", "value": { "status": "5", "error_text": "Internal Error" } }, "not-found": { "summary": "Request not found (this also occurs immediately after completion, wait 60 seconds and try again)", "value": { "status": "101", "error_text": "No response found" } } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/searchResponse" }, { "$ref": "#/components/schemas/searchErrorResponse" } ] } }, "text/xml": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/searchResponse" }, { "$ref": "#/components/schemas/searchErrorResponse" } ] } } } } } } }, "/control/{format}": { "post": { "description": "Control the progress of your Verify requests. To cancel an existing Verify request, or to trigger the next verification event:\n\n\n1. Send a Verify control request with the appropriate command (`cmd`) for what you want to achieve.\n\n2. Check the `status` in the response.\n\n\n*Note that this endpoint is available by `GET` request as well as `POST`.*", "operationId": "verifyControl", "tags": [ "Verify Control" ], "summary": "Verify Control", "parameters": [ { "$ref": "#/components/parameters/format" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/controlRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "examples": { "success-cancel": { "summary": "The request has been cancelled", "value": { "status": "0", "command": "cancel" } }, "success-trigger": { "summary": "The next event has been triggered", "value": { "status": "0", "command": "trigger_next_event" } }, "throttled": { "summary": "Request limit exceeded", "value": { "status": "1", "error_text": "Throttled" } }, "missing-param": { "summary": "Missing a parameter", "value": { "status": "2", "error_text": "Missing request_id" } }, "invalid-param": { "summary": "Invalid parameter", "value": { "status": "3", "error_text": "Invalid value for param: request_id" } }, "invalid-creds": { "summary": "Invalid credentials", "value": { "status": "4", "error_text": "Bad credentials" } }, "internal-error": { "summary": "Internal Error", "value": { "status": "5", "error_text": "Internal Error" } }, "cancel-early": { "summary": "Cancellation requested less than 30 seconds into the request", "value": { "status": "19", "error_text": "Verification request ['abcdef0123456789abcdef0123456789'] can't be cancelled within the first 30 seconds." } }, "cancel-late": { "summary": "Cancellation requested after too many retry attempts", "value": { "status": "19", "error_text": "Verification request ['abcdef0123456789abcdef0123456789'] can't be cancelled now. Too many attempts to re-deliver have already been made." } }, "trigger-end": { "summary": "No more events to trigger", "value": { "status": "19", "error_text": "No more events are left to execute for the request ['abcdef0123456789abcdef0123456789']" } } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/controlResponse" }, { "$ref": "#/components/schemas/controlErrorResponse" } ] } }, "text/xml": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/controlResponse" }, { "$ref": "#/components/schemas/controlErrorResponse" } ] } } } } } } }, "/psd2/{format}": { "post": { "operationId": "verifyRequestWithPSD2", "tags": [ "Verify Requests" ], "summary": "PSD2 (Payment Services Directive 2) Request", "description": "Use Verify request to generate and send a PIN to your user to authorize a payment:\n1. Create a request to send a verification code to your user.\n2. Check the `status` field in the response to ensure that your request was successful (zero is success).\n3. Use the `request_id` field in the response for the Verify check.\n(Please note that XML format is not supported for the Payment Services Directive endpoint at this time.)", "parameters": [ { "$ref": "#/components/parameters/format" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/psd2Request" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/requestResponse" }, { "$ref": "#/components/schemas/requestErrorResponse" } ] } } } } } } }, "/network-unblock": { "post": { "operationId": "networkUnblock", "summary": "Request a network unblock", "description": "Request to unblock a network that has been blocked due to potential fraud detection.", "x-note": { "type": "alert", "icon": "warning-line", "header": "Network Unblock is switched off by default.", "description": "Please contact Sales to enable the Network Unblock API for your account." }, "tags": [ "Fraud Management" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/networkUnblock" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/networkUnblockResponseOk" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/networkUnblockResponseForbidden" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/networkUnblockResponseNotFound" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/networkUnblockResponseUnprocessableNetwork" }, { "$ref": "#/components/schemas/networkUnblockResponseInvalidDuration" } ] } } } }, "429": { "description": "Rate Limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorThrottled" } } } } } } } }, "components": { "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic" } }, "parameters": { "format": { "name": "format", "required": true, "in": "path", "description": "The response format.", "schema": { "type": "string", "enum": [ "json", "xml" ] }, "example": "json" } }, "schemas": { "estimated_price_messages_sent": { "type": "string", "description": "This field may not be present, depending on your pricing model. The\nvalue indicates the cost (in EUR) of the calls made and messages sent\nfor the verification process. This value may be updated during and\nshortly after the request completes because user input events can\noverlap with message/call events. When this field is present, the total\ncost of the verification is the sum of this field and the `price` field.\n", "example": "0.03330000" }, "networkUnblock": { "type": "object", "properties": { "network": { "type": "string", "description": "The Network code", "example": 32526 }, "unblock_duration": { "type": "integer", "required": [ "false" ], "minimum": 0, "maximum": 86400, "default": 3600, "description": "An optional duration the unblock will be applied for in seconds", "example": "3600" } } }, "verifyRequest": { "type": "object", "required": [ "number", "brand" ], "properties": { "number": { "type": "string", "description": "The mobile or landline phone number to verify. Unless you are setting `country` explicitly, this number must be in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "example": "447700900000" }, "country": { "description": "If you do not provide `number` in international format or you are not sure if `number` is correctly formatted, specify the two-character country code in `country`. Verify will then format the number for you.", "type": "string", "example": "GB" }, "brand": { "description": "An 18-character alphanumeric string you can use to personalize the verification request SMS body, to help users identify your company or application name. For example: \"Your `Acme Inc` PIN is ...\"", "type": "string", "maxLength": 18, "example": "Acme Inc" }, "sender_id": { "description": "An 11-character alphanumeric string that represents the [identity of the sender](https://developer.nexmo.com/messaging/sms/guides/custom-sender-id) of the verification request. Depending on the destination of the phone number you are sending the verification SMS to, restrictions might apply.", "type": "string", "maxLength": 11, "default": "VERIFY", "example": "ACME" }, "code_length": { "description": "The length of the verification code.", "type": "integer", "enum": [ 4, 6 ], "default": 4, "example": 6 }, "lg": { "description": "By default, the SMS or text-to-speech (TTS) message is generated in the locale that matches the `number`. For example, the text message or TTS message for a `33*` number is sent in French. Use this parameter to explicitly control the language used for the Verify request. A list of languages is available: ", "example": "en-us", "type": "string", "default": "en-us", "enum": [ "ar-xa", "cs-cz", "cy-cy", "cy-gb", "da-dk", "de-de", "el-gr", "en-au", "en-gb", "en-in", "en-us", "es-es", "es-mx", "es-us", "fi-fi", "fil-ph", "fr-ca", "fr-fr", "hi-in", "hu-hu", "id-id", "is-is", "it-it", "ja-jp", "ko-kr", "nb-no", "nl-nl", "pl-pl", "pt-br", "pt-pt", "ro-ro", "ru-ru", "sv-se", "th-th", "tr-tr", "vi-vn", "yue-cn", "zh-cn", "zh-tw" ] }, "pin_expiry": { "description": "How long the generated verification code is valid for, in seconds. When you specify both `pin_expiry` and `next_event_wait` then `pin_expiry` must be an integer multiple of `next_event_wait` otherwise `pin_expiry` is defaulted to equal next_event_wait. See [changing the event timings](https://developer.nexmo.com/verify/verify-v1/guides/changing-default-timings).", "type": "integer", "minimum": 60, "maximum": 3600, "default": 300, "example": 240 }, "next_event_wait": { "description": "Specifies the wait time in seconds between attempts to deliver the verification code.", "type": "integer", "minimum": 60, "maximum": 900, "default": 300, "example": 120 }, "workflow_id": { "description": "Selects the predefined sequence of SMS and TTS (Text To Speech) actions to use in order to convey the PIN to your user. For example, an id of 1 identifies the workflow SMS - TTS - TTS. For a list of all workflows and their associated ids, please visit the [developer portal](https://developer.nexmo.com/verify/verify-v1/guides/workflows-and-events).", "type": "integer", "default": 1, "enum": [ 1, 2, 3, 4, 5, 6, 7 ], "example": 4 }, "pin_code": { "type": "string", "minimum": 4, "maximum": 10, "description": "A custom PIN to send to the user. If a PIN is not provided, Verify will generate a random PIN for you. This feature is not enabled by default - please discuss with your Account Manager if you would like it enabled. If this feature is not enabled on your account, error status `20` will be returned.", "example": "AKFG-3424" } } }, "requestResponse": { "type": "object", "description": "Success", "xml": { "name": "verify_response" }, "properties": { "request_id": { "type": "string", "description": "The unique ID of the Verify request. You need this `request_id` for the Verify check.", "maxLength": 32, "example": "abcdef0123456789abcdef0123456789" }, "status": { "type": "string", "description": "Indicates the outcome of the request; zero is success", "example": "0" } } }, "networkUnblockResponseOk": { "type": "object", "description": "Success", "xml": { "name": "networkUnblockResponse" }, "properties": { "network": { "type": "string", "description": "The unique network ID", "example": "23410" }, "unblocked_until": { "type": "string", "description": "Gives the DateTime when the unblock will expire.", "example": "2024-04-22T08:34:58Z" } } }, "networkUnblockResponseNotFound": { "type": "object", "description": "Not Found", "xml": { "name": "networkUnblockResponseNotFound" }, "properties": { "type": { "type": "string", "description": "A URL link to the API documentation for this type of error.", "example": "https://developer.vonage.com/api-errors#bad-request" }, "title": { "type": "string", "description": "Full string text of the HTTP error code.", "example": "Not Found" }, "detail": { "type": "string", "description": "Verbose description of the server error.", "example": "The network you provided does not have an active block." }, "instance": { "type": "string", "description": "InstanceID", "example": "bf0ca0bf927b3b52e3cb03217e1a1ddf" } } }, "networkUnblockResponseForbidden": { "type": "object", "description": "Forbidden", "xml": { "name": "networkUnblockResponseForbidden" }, "properties": { "type": { "type": "string", "description": "A URL link to the API documentation for this type of error.", "example": "https://developer.vonage.com/api-errors#forbidden" }, "title": { "type": "string", "description": "Full string text of the HTTP error code.", "example": "Forbidden" }, "detail": { "type": "string", "description": "Verbose description of the server error.", "example": "Your account does not have permission to perform this action." }, "instance": { "type": "string", "description": "The Instance ID", "example": "bf0ca0bf927b3b52e3cb03217e1a1ddf" } } }, "networkUnblockResponseUnprocessableNetwork": { "type": "object", "description": "Invalid Network", "xml": { "name": "networkUnblockResponseUnprocessableNetwork" }, "properties": { "type": { "type": "string", "description": "A URL link to the API documentation for this type of error.", "example": "https://developer.vonage.com/api-errors#invalid-paramater" }, "title": { "type": "string", "description": "Full string text of the HTTP error code.", "example": "Network not found." }, "detail": { "type": "string", "description": "Verbose description of the server error.", "example": "Network is not in the request." }, "instance": { "type": "string", "description": "The Instance ID", "example": "bf0ca0bf927b3b52e3cb03217e1a1ddf" }, "invalid_parameters": { "type": "array", "description": "Detailed payload of errors.", "items": { "type": "object", "properties": { "name": { "description": "The name of the parameter.", "example": "network", "type": "string" }, "reason": { "description": "The reason for the parameter error.", "example": "Network not found", "type": "string" } } } } } }, "networkUnblockResponseInvalidDuration": { "type": "object", "description": "Invalid Duration", "xml": { "name": "networkUnblockResponseInvalidDuration" }, "properties": { "type": { "type": "string", "description": "A URL link to the API documentation for this type of error.", "example": "https://developer.vonage.com/api-errors#invalid-paramater" }, "title": { "type": "string", "description": "Full string text of the HTTP error code.", "example": "Invalid unblock_duration parameter" }, "detail": { "type": "string", "description": "Verbose description of the server error.", "example": "Unblock duration is invalid." }, "instance": { "type": "string", "description": "The Instance ID", "example": "bf0ca0bf927b3b52e3cb03217e1a1ddf" }, "invalid_parameters": { "type": "array", "description": "Detailed payload of errors.", "items": { "type": "object", "properties": { "name": { "description": "The name of the parameter.", "example": "network", "type": "string" }, "reason": { "description": "The reason for the parameter error.", "example": "Network not found", "type": "string" } } } } } }, "requestErrorResponse": { "type": "object", "description": "Error", "xml": { "name": "verify_response" }, "properties": { "request_id": { "type": "string", "description": "The unique ID of the Verify request. This may be blank in an error situation.", "maxLength": 32, "example": "" }, "status": { "type": "string", "example": "2", "enum": [ "0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "15", "20", "29" ], "description": "Code | Text | Description\n-- | -- | --\n0 | Success | The request was successfully accepted by Vonage.\n1 | Throttled | You are trying to send more than the maximum of 30 requests per second.\n2 | Your request is incomplete and missing the mandatory parameter `$parameter` | The stated parameter is missing.\n3 | Invalid value for parameter `$parameter` | Invalid value for parameter. If you see Facility not allowed in the error text, check that you are using the correct Base URL in your request.\n4 | Invalid credentials were provided | The supplied API key or secret in the request is either invalid or disabled.\n5 | Internal Error | An error occurred processing this request in the Cloud Communications Platform.\n6 | The Vonage platform was unable to process this message for the following reason: `$reason` | The request could not be routed.\n7 | The number you are trying to verify is blacklisted for verification. | Returns a `network` property but no `request_id` will be present in the response.\n8 | The api_key you supplied is for an account that has been barred from submitting messages. |\n9 | Partner quota exceeded | Your account does not have sufficient credit to process this request.\n10 | Concurrent verifications to the same number are not allowed. | This will return a `request_id`.\n15 | The destination number is not in a supported network | The request has been rejected. Find out more about this error in the [Knowledge Base](https://api.support.vonage.com/hc/en-us/articles/360018406532-Verify-On-demand-Service-to-High-Risk-Countries)\n20 | This account does not support the parameter: pin_code. | Only certain accounts have the ability to set the `pin_code`. Please contact your account manager for more information.\n29 | Non-Permitted Destination | Your Vonage account is still in demo mode. While in demo mode you must add target numbers to the approved list for your account. Add funds to your account to remove this limitation.\n" }, "error_text": { "type": "string", "description": "If `status` is non-zero, this explains the error encountered.", "example": "Your request is incomplete and missing the mandatory parameter `number`" }, "network": { "type": "string", "description": "The Network ID of the blocking network, if relevant to the error.", "example": "244523" } } }, "checkRequest": { "type": "object", "required": [ "request_id", "code" ], "properties": { "request_id": { "description": "The Verify request to check. This is the `request_id` you received in the response to the Verify request.", "type": "string", "maxLength": 32, "example": "abcdef0123456789abcdef0123456789" }, "code": { "description": "The verification code entered by your user.", "type": "string", "minLength": 4, "maxLength": 6, "example": "1234" }, "ip_address": { "description": "(This field is no longer used)", "type": "string", "deprecated": true, "example": "123.0.0.255" } } }, "checkResponse": { "type": "object", "description": "Success", "properties": { "request_id": { "type": "string", "description": "The `request_id` that you received in the response to the Verify request and used in the Verify check request.", "example": "abcdef0123456789abcdef0123456789" }, "event_id": { "type": "string", "description": "The ID of the verification event, such as an SMS or TTS call.", "example": "0A00000012345678" }, "status": { "type": "string", "description": "A value of `0` indicates that your user entered the correct code. If it is non-zero, check the `error_text`.", "example": "0" }, "price": { "type": "string", "description": "The cost incurred for this request.", "example": "0.10000000" }, "currency": { "type": "string", "description": "The currency code.", "example": "EUR" }, "estimated_price_messages_sent": { "$ref": "#/components/schemas/estimated_price_messages_sent" } }, "xml": { "name": "verify_response" } }, "checkErrorResponse": { "type": "object", "description": "Error", "properties": { "request_id": { "type": "string", "description": "The `request_id` that you received in the response to the Verify request and used in the Verify check request.", "example": "abcdef0123456789abcdef0123456789" }, "status": { "type": "string", "example": "16", "enum": [ "0", "1", "2", "3", "4", "5", "6", "16", "17" ], "description": "Code | Text | Description\n-- | -- | --\n0 | Success | The request was successfully accepted by Vonage.\n1 | Throttled | You are trying to send more than the maximum of 30 requests per second.\n2 | Your request is incomplete and missing the mandatory parameter `$parameter` | The stated parameter is missing.\n3 | Invalid value for parameter `$parameter` | Invalid value for parameter. If you see Facility not allowed in the error text, check that you are using the correct Base URL in your request.\n4 | Invalid credentials were provided | The supplied API key or secret in the request is either invalid or disabled.\n5 | Internal Error | An error occurred processing this request in the Cloud Communications Platform.\n6 | The Vonage platform was unable to process this message for the following reason: `$reason` | The request could not be routed.\n16 | The code inserted does not match the expected value |\n17 | The wrong code was provided too many times | You can run Verify check on a specific `request_id` up to three times unless a new verification code is generated. If you check a request more than three times, it is set to FAILED and you cannot check it again.\n" }, "error_text": { "type": "string", "description": "If the `status` is non-zero, this explains the error encountered.", "example": "The code inserted does not match the expected value" } }, "xml": { "name": "verify_response" } }, "searchResponse": { "xml": { "name": "verify_request" }, "type": "object", "description": "Success", "properties": { "request_id": { "type": "string", "description": "The `request_id` that you received in the response to the Verify request and used in the Verify search request.", "example": "abcdef0123456789abcdef0123456789" }, "account_id": { "type": "string", "description": "The Vonage account ID the request was for.", "example": "abcdef01" }, "status": { "type": "string", "example": "IN PROGRESS", "enum": [ "IN PROGRESS", "SUCCESS", "FAILED", "EXPIRED", "CANCELLED" ], "description": "Code | Description\n-- | --\nIN PROGRESS | The search is still in progress.\nSUCCESS | Your user entered a correct verification code.\nFAILED | Your user entered an incorrect code more than three times.\nEXPIRED | Your user did not enter a code before the `pin_expiry` time elapsed.\nCANCELLED | The verification process was cancelled by a Verify control request.\n" }, "number": { "type": "string", "description": "The phone number this verification request was used for.", "example": "447700900000" }, "price": { "type": "string", "description": "The cost incurred for this verification request.", "example": "0.10000000" }, "currency": { "type": "string", "description": "The currency code.", "example": "EUR" }, "sender_id": { "type": "string", "description": "The `sender_id` you provided in the Verify request.", "default": "verify", "example": "mySenderId" }, "date_submitted": { "type": "string", "description": "The date and time the verification request was submitted, in the following format YYYY-MM-DD HH:MM:SS.", "example": "2020-01-01 12:00:00" }, "date_finalized": { "type": "string", "description": "The date and time the verification request was completed. This response parameter is in the following format YYYY-MM-DD HH:MM:SS.", "example": "2020-01-01 12:00:00" }, "first_event_date": { "type": "string", "description": "The time the first verification attempt was made, in the following format YYYY-MM-DD HH:MM:SS.", "example": "2020-01-01 12:00:00" }, "last_event_date": { "type": "string", "description": "The time the last verification attempt was made, in the following format YYYY-MM-DD HH:MM:SS.", "example": "2020-01-01 12:00:00" }, "checks": { "type": "array", "xml": { "wrapped": true }, "description": "The list of checks made for this verification and their outcomes.", "items": { "type": "object", "xml": { "name": "check" }, "properties": { "date_received": { "type": "string", "description": "The date and time this check was received (in the format YYYY-MM-DD HH:MM:SS)", "example": "2020-01-01 12:00:00" }, "code": { "type": "string", "description": "The code supplied with this check request", "example": "987654" }, "status": { "type": "string", "enum": [ "VALID", "INVALID" ] }, "ip_address": { "type": "string", "description": "The IP address, if available (this field is no longer used).", "deprecated": true, "example": "123.0.0.255" } } } }, "events": { "type": "array", "xml": { "wrapped": true }, "description": "The events that have taken place to verify this number, and their unique identifiers.", "items": { "type": "object", "xml": { "name": "event" }, "properties": { "type": { "type": "string", "enum": [ "tts", "sms" ] }, "id": { "type": "string" } } } }, "estimated_price_messages_sent": { "$ref": "#/components/schemas/estimated_price_messages_sent" } } }, "searchErrorResponse": { "xml": { "name": "verify_request" }, "type": "object", "description": "Error", "properties": { "request_id": { "type": "string", "description": "The `request_id` that you received in the response to the Verify request and used in the Verify search request. May be empty in an error situation.", "example": "abcdef0123456789abcdef0123456789" }, "status": { "type": "string", "example": "IN PROGRESS", "enum": [ "IN PROGRESS", "FAILED", "EXPIRED", "CANCELLED", "101" ], "description": "Code | Description\n-- | --\nIN PROGRESS | The search is still in progress.\nSUCCESS | Your user entered a correct verification code.\nFAILED | Your user entered an incorrect code more than three times.\nEXPIRED | Your user did not enter a code before the `pin_expiry` time elapsed.\nCANCELLED | The verification process was cancelled by a Verify control request.\n101 | You supplied an invalid `request_id`, or the data is not available. Note that for recently-completed requests, there can be a delay of up to 1 minute before the results are available in search.\n" }, "error_text": { "type": "string", "description": "If `status` is not `SUCCESS`, this message explains the issue encountered.", "example": "No response found" } } }, "controlRequest": { "type": "object", "required": [ "request_id", "cmd" ], "properties": { "request_id": { "description": "The `request_id` you received in the response to the Verify request.", "type": "string", "example": "abcdef0123456789abcdef0123456789" }, "cmd": { "description": "The possible commands are `cancel` to request cancellation of the verification process, or `trigger_next_event` to advance to the next verification event (if any). 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.", "type": "string", "enum": [ "cancel", "trigger_next_event" ], "example": "cancel" } } }, "controlResponse": { "type": "object", "description": "Success", "xml": { "name": "response" }, "properties": { "status": { "type": "string", "example": "0", "description": "`cmd` | Code | Description\n-- | -- | --\nAny | 0 | Success\n" }, "command": { "type": "string", "description": "The `cmd` you sent in the request.", "enum": [ "cancel", "trigger_next_event" ], "example": "cancel" } } }, "controlErrorResponse": { "type": "object", "description": "Error", "xml": { "name": "response" }, "properties": { "status": { "type": "string", "example": "6", "enum": [ "0", "1", "2", "3", "4", "5", "6", "8", "9", "19" ], "description": "Code | Text | Description\n-- | -- | --\n0 | Success | The request was successfully accepted by Vonage.\n1 | Throttled | You are trying to send more than the maximum of 30 requests per second.\n2 | Your request is incomplete and missing the mandatory parameter `$parameter` | The stated parameter is missing.\n3 | Invalid value for parameter `$parameter` | Invalid value for parameter. If you see Facility not allowed in the error text, check that you are using the correct Base URL in your request.\n4 | Invalid credentials were provided | The supplied API key or secret in the request is either invalid or disabled.\n5 | Internal Error | An error occurred processing this request in the Cloud Communications Platform.\n6 | The Vonage platform was unable to process this message for the following reason: `$reason` | The request could not be routed.\n8 | The api_key you supplied is for an account that has been barred from submitting messages. |\n9 | Partner quota exceeded | Your account does not have sufficient credit to process this request.\n19 | For `cancel`: Either you have not waited at least 30 secs after sending a Verify request before cancelling or Verify has made too many attempts to deliver the verification code for this request and you must now wait for the process to complete. For `trigger_next_event`: All attempts to deliver the verification code for this request have completed and there are no remaining events to advance to.\n" }, "error_text": { "type": "string", "description": "If the `status` is non-zero, this explains the error encountered.", "example": "The requestId 'abcdef0123456789abcdef' does not exist or its no longer active." } } }, "psd2Request": { "type": "object", "required": [ "number", "payee", "amount" ], "properties": { "number": { "type": "string", "description": "The mobile or landline phone number to verify. Unless you are setting `country` explicitly, this number must be in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "example": "447700900000" }, "country": { "description": "If you do not provide `number` in international format or you are not sure if `number` is correctly formatted, specify the two-character country code in `country`. Verify will then format the number for you.", "type": "string", "example": "GB" }, "payee": { "description": "An alphanumeric string to indicate to the user the name of the recipient that they are confirming a payment to.", "type": "string", "maxLength": 18, "example": "Acme Inc" }, "amount": { "description": "The decimal amount of the payment to be confirmed, in Euros", "type": "number", "format": "float", "example": "48.00" }, "code_length": { "description": "The length of the verification code.", "type": "integer", "enum": [ 4, 6 ], "default": 4, "example": 6 }, "lg": { "description": "By default, the SMS or text-to-speech (TTS) message is generated in the locale that matches the `number`. For example, the text message or TTS message for a `33*` number is sent in French. Use this parameter to explicitly control the language used.\n*Note: Voice calls in English for `bg-bg`, `ee-et`, `ga-ie`, `lv-lv`, `lt-lt`, `mt-mt`, `sk-sk`, `sk-si`", "example": "es-es", "type": "string", "default": "en-gb", "enum": [ "en-gb", "bg-bg", "cs-cz", "da-dk", "de-de", "ee-et", "el-gr", "es-es", "fi-fi", "fr-fr", "ga-ie", "hu-hu", "it-it", "lv-lv", "lt-lt", "mt-mt", "nl-nl", "pl-pl", "sk-sk", "sl-si", "sv-se" ] }, "pin_expiry": { "description": "How long the generated verification code is valid for, in seconds. When you specify both `pin_expiry` and `next_event_wait` then `pin_expiry` must be an integer multiple of `next_event_wait` otherwise `pin_expiry` is defaulted to equal next_event_wait. See [changing the event timings](https://developer.nexmo.com/verify/verify-v1/guides/changing-default-timings).", "type": "integer", "minimum": 60, "maximum": 3600, "default": 300, "example": 240 }, "next_event_wait": { "description": "Specifies the wait time in seconds between attempts to deliver the verification code.", "type": "integer", "minimum": 60, "maximum": 900, "default": 300, "example": 120 }, "workflow_id": { "description": "Selects the predefined sequence of SMS and TTS (Text To Speech) actions to use in order to convey the PIN to your user. For example, an id of 1 identifies the workflow SMS - TTS - TTS. For a list of all workflows and their associated ids, please visit the [developer portal](https://developer.nexmo.com/verify/verify-v1/guides/workflows-and-events).", "type": "integer", "default": 1, "enum": [ 1, 2, 3, 4, 5, 6, 7 ], "example": 4 } } }, "ErrorThrottled": { "type": "object", "required": [ "type", "title", "detail", "instance" ], "properties": { "type": { "type": "string", "description": "Link to error / remediation options", "example": "https://developer.vonage.com/api-errors/verify#rate-limit" }, "title": { "type": "string", "description": "Generic error message", "example": "Rate Limit Hit" }, "detail": { "type": "string", "description": "Additional information about the error", "example": "Please wait, then retry your request" }, "instance": { "type": "string", "description": "Internal Trace ID", "example": "bf0ca0bf927b3b52e3cb03217e1a1ddf" } } } } } }