openapi: 3.2.0 info: title: Vonage Verify Control 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 Control 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 Control description: Verify Control paths: /control/{format}: post: description: 'Control the progress of your Verify requests. To cancel an existing Verify request, or to trigger the next verification event: 1. Send a Verify control request with the appropriate command (`cmd`) for what you want to achieve. 2. Check the `status` in the response. *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' servers: - url: https://api.nexmo.com/verify components: schemas: controlResponse: type: object description: Success xml: name: response properties: status: type: string example: '0' description: '`cmd` | Code | Description -- | -- | -- Any | 0 | Success ' 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 -- | -- | -- 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. 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. 19 | 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. ' 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. 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 parameters: format: name: format required: true in: path description: The response format. schema: type: string enum: - json - xml example: json 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