openapi: 3.2.0 info: title: Vonage Verify Requests API version: 1.2.4 contact: name: Vonage DevRel email: devrel@vonage.com url: https://developer.nexmo.com/ license: name: The MIT License (MIT) url: https://opensource.org/licenses/MIT termsOfService: https://www.nexmo.com/terms-of-use x-label: Deprecated 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-metaTitle: Vonage Verify v1.0 API Reference | Vonage API Documentation description: 'Operations tagged Verify Requests across 2 of this provider''s published API definitions: vonage-verify-openapi.json, vonage-verify-openapi.yml. Each path carries the servers of the definition it was published in.' servers: - url: https://api.nexmo.com/verify security: - basicAuth: [] tags: - name: Verify Requests description: Verify Requests 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: 1. Create a request to send a verification code to your user. 2. Check the `status` field in the response to ensure that your request was successful (zero is success). 3. Use the `request_id` field in the response for the Verify check. *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' servers: - url: https://api.nexmo.com/verify /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: 1. Create a request to send a verification code to your user. 2. Check the `status` field in the response to ensure that your request was successful (zero is success). 3. Use the `request_id` field in the response for the Verify check. (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' servers: - url: https://api.nexmo.com/verify components: parameters: format: name: format required: true in: path description: The response format. schema: type: string enum: - json - xml example: json schemas: 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' 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 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. *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 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 -- | -- | -- 0 | Success | The request was successfully accepted by Vonage. 1 | Throttled | You are trying to send more than the maximum of 30 requests per second. 2 | Your request is incomplete and missing the mandatory parameter `$parameter` | The stated parameter is missing. 3 | 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. 4 | Invalid credentials were provided | The supplied API key or secret in the request is either invalid or disabled. 5 | Internal Error | An error occurred processing this request in the Cloud Communications Platform. 6 | The Vonage platform was unable to process this message for the following reason: `$reason` | The request could not be routed. 7 | 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. 8 | The api_key you supplied is for an account that has been barred from submitting messages. | 9 | Partner quota exceeded | Your account does not have sufficient credit to process this request. 10 | Concurrent verifications to the same number are not allowed. | This will return a `request_id`. 15 | 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) 20 | 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. 29 | 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. ' 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' securitySchemes: basicAuth: type: http scheme: basic externalDocs: description: More information on the Verify product on our Developer Portal url: https://developer.nexmo.com/verify/overview x-refined-from: - vonage-verify-openapi.json - vonage-verify-openapi.yml x-errors: validation: description: The provided payload is invalid resolution: 'Modify your request to provide a valid payload. * Minimum 8 characters * Maximum 25 characters * Minimum 1 lower case character * Minimum 1 upper case character * Minimum 1 digit ' link: text: View API reference url: /api/account#createAPISecret delete-last-secret: description: You can not delete your only API secret resolution: Add another API secret before deleting this one