Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
751 lines (734 sloc) 28 KB
openapi: 3.0.0
servers:
- url: 'https://api.nexmo.com/verify'
info:
title: Nexmo Verify API
version: 1.0.0
description: >-
The Verify API helps you to implement 2FA (two-factor authentication) in your applications.
This is useful for:
* Protecting against spam, by preventing spammers from creating multiple accounts
* Monitoring suspicious activity, by forcing an account user to verify ownership of a number
* Ensuring that you can reach your users at any time because you have their correct phone number
contact:
name: Nexmo DevRel
email: devrel@nexmo.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:
url: 'https://developer.nexmo.com/api/verify'
security:
- apiKey: []
apiSecret: []
tags:
- name: Verify Request
description: >-
Generate and send a PIN to your user. You use the `request_id` in the
response for the Verify check.
- name: Verify Check
description: >-
Confirm that the PIN you received from your user matches the one sent by
Nexmo as a result of your Verify request.
- name: Verify Search
description: Lookup the status of one or more requests.
- name: Verify Control
description: Control the progress of your Verify Requests.
paths:
'/{format}':
get:
description: >-
To use Verify request you:
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.
operationId: verifyRequest
summary: Verify request
tags:
- Verify Request
parameters:
- $ref: '#/components/parameters/format'
- name: number
required: true
in: query
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.
schema:
type: string
example: '447700900000'
- name: country
required: false
in: query
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.
schema:
type: string
example: GB
- name: brand
required: true
in: query
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 ..."
schema:
type: string
maxLength: 18
example: Acme Inc
- name: sender_id
required: false
in: query
description: >-
An 11-character alphanumeric string that represents the [identify the sender](/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.
schema:
type: string
maxLength: 11
default: VERIFY
example: VERIFY
- name: code_length
required: false
in: query
description: The length of the verification code.
schema:
type: integer
enum:
- 4
- 6
default: 4
example: 4
- name: lg
required: false
in: query
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, accent and gender used
for the Verify request.
example: en-us
schema:
type: string
default: en-us
enum:
- de-de
- en-au
- en-gb
- en-us
- en-in
- es-es
- es-mx
- es-us
- fr-ca
- fr-fr
- is-is
- it-it
- ja-jp
- ko-kr
- nl-nl
- pl-pl
- pt-pt
- pt-br
- ro-ro
- ru-ru
- sv-se
- tr-tr
- zh-cn
- zh-tw
x-ms-enum:
values:
- value: de-de
description: 'German, German (female / male)'
- value: en-au
description: 'English, Australian (female / male)'
- value: en-gb
description: 'English, UK (female / male)'
- value: en-us
description: 'English, US (female / male)'
- value: en-in
description: 'English, Indian (female)'
- value: es-es
description: 'Spanish, Spanish (female / male)'
- value: es-mx
description: 'Spanish, Mexican (female)'
- value: es-us
description: 'Spanish, US (female / male)'
- value: fr-ca
description: 'French, Canadian (female)'
- value: fr-fr
description: 'French, French (female / male)'
- value: is-is
description: 'Icelandic, Icelandic (female / male)'
- value: it-it
description: 'Italian, Italian (female / male)'
- value: ja-jp
description: 'Japanese, Japanese (female / male)'
- value: ko-kr
description: 'Korean, Korean (female / male)'
- value: nl-nl
description: 'Dutch, Netherlands (female / male)'
- value: pl-pl
description: 'Polish, Polish (female / male)'
- value: pt-pt
description: 'Portuguese, Portuguese (male)'
- value: pt-br
description: 'Portuguese, Brazilian (female / male)'
- value: ro-ro
description: 'Romanian, Romanian (female)'
- value: ru-ru
description: 'Russian, Russian (female)'
- value: sv-se
description: 'Swedish, Sweden (female)'
- value: tr-tr
description: 'Turkish, Turkish (female)'
- value: zh-cn
description: 'Chinese (Mandarin), Simplified Chinese (female / male)'
- value: zh-tw
description: >-
Chinese, Traditional. Text only. If you request Taiwanese
(`zh-tw`), the text message will be sent in Traditional
Chinese, but the voice call uses a female voice speaking
English with a Chinese accent.
- name: require_type
required: false
in: query
description: >-
Restrict verification to a certain network type. You must
contact [support@nexmo.com](mailto:support@nexmo.com) to
enable this feature.
schema:
type: string
default: All
enum:
- All
- Mobile
- Landline
example: Mobile
- name: pin_expiry
required: false
in: query
description: >-
How log 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 set to equal next_event_wait. See [changing the default event timings](/verify/guides/changing-default-timings).
schema:
type: integer
minimum: 60
maximum: 3600
default: 300
example: 300
- name: next_event_wait
required: false
in: query
description: >-
Specifies the wait time in seconds between attempts to deliver the
verification code.
schema:
type: integer
minimum: 60
maximum: 900
default: 300
example: 300
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/requestResponse'
text/xml:
schema:
$ref: '#/components/schemas/requestResponse'
'/check/{format}':
get:
description: >-
To use Verify check you:
1. Send the verification code that your user supplied, with the corresponding `request_id` from the Verify request.
2. Check the `status` of the response to determine if the code the user supplied matches the one sent by Nexmo.
operationId: verifyCheck
summary: Verify check
tags:
- Verify Check
parameters:
- $ref: '#/components/parameters/format'
- name: request_id
required: true
in: query
description: >-
The Verify request to check. This is the
`request_id` you received in the response to the Verify request.
schema:
type: string
maxLength: 32
#example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
example: aaaaaaaa-bbbb-...
- name: code
required: true
in: query
description: The verification code entered by your user.
schema:
type: string
minLength: 4
maxLength: 6
example: '1234'
- name: ip_address
required: false
in: query
description: >-
The IP address used by your user when they entered the verification code. Nexmo
uses this information to identify fraud and spam. This ultimately benefits all Nexmo customers.
schema:
type: string
example: 123.0.0.255
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/checkResponse'
text/xml:
schema:
$ref: '#/components/schemas/checkResponse'
'/search/{format}':
get:
description: >-
To check the status of past or current verification requests:
1. Send a Verify Search request containing the `request_id`s of the
verification requests you are interested in
2. Use the `status` of each verification request in the `checks` array of the response object to determine the outcome
operationId: verifySearch
summary: Verify search
tags:
- Verify Search
parameters:
- $ref: '#/components/parameters/format'
- name: request_id
required: false
in: query
description: The `request_id` you received in the Verify Request Response.
schema:
type: string
#example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
example: aaaaaaaa-bbbb-...
- 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.
schema:
type: array
items:
type: string
#example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
example: aaaaaaaa-bbbb-...
maxItems: 10
style: form
explode: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/searchResponse'
text/xml:
schema:
$ref: '#/components/schemas/searchResponse'
'/control/{format}':
get:
description: |-
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 response.
operationId: verifyControl
summary: Verify control
tags:
- Verify Control
parameters:
- $ref: '#/components/parameters/format'
- name: request_id
required: true
in: query
description: 'The `request_id` you received in the response to the Verify request.'
schema:
type: string
#example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
example: aaaaaaaa-bbbb-...
- name: cmd
required: true
in: query
description: >-
The command to execute, depending on whether you want to cancel
the verification process, or advance to the next verification event.
You must wait at least 30 seconds before cancelling a Verify request.
schema:
type: string
enum:
- cancel
- trigger_next_event
x-ms-enum:
values:
- value: cancel
description: stop the request
- value: trigger_next_event
description: advance the request to the next part of the process.
example: cancel
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/controlResponse'
text/xml:
schema:
$ref: '#/components/schemas/controlResponse'
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
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: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
example: aaaaaaaa-bbbb-...
status:
type: string
#description: The response code that indicates success or failure of the Verify request. A non-zero value indicates failure.
example: '0'
enum:
- '0'
- '1'
- '2'
- '3'
- '4'
- '5'
- '6'
- '7'
- '8'
- '9'
- '10'
- '15'
- '16'
- '17'
- '18'
- '19'
- '101'
description: |
Code | Text | Description
-- | -- | --
0 | Success | The request was successfully accepted by Nexmo.
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 Nexmo 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. |
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 |
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://help.nexmo.com/hc/en-us/articles/360018406532-Verify-On-demand-Service-to-High-Risk-Countries)
16 | The code inserted does not match the expected value |
17 | 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.
18 | Too many request_ids provided | You added more than the maximum ten `request_id`s to your request.
19 | No more events are left to execute for this request |
101 | No request found | There are no matching verify requests.
# x-ms-enum:
# values:
# - value: '0'
# description: The request was successfully accepted by Nexmo.
# - value: '1'
# description: >-
# You are trying to send more than the maximum of 30 requests
# per second.
# - value: '2'
# description: The stated parameter is missing.
# - value: '3'
# description: >-
# 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.
# - value: '4'
# description: >-
# The supplied API key or secret in the request is either
# invalid or disabled.
# - value: '5'
# description: >-
# An error occurred processing this request in the Cloud
# Communications Platform.
# - value: '6'
# description: The request could not be routed.
# - value: '7'
# description: >-
# The number you are trying to verify is blacklisted for
# verification
# - value: '8'
# description: >-
# The api_key you supplied is for an account that has been
# barred from submitting messages
# - value: '9'
# description: >-
# Your account does not have sufficient credit to process this
# request.
# - value: '10'
# description: Concurrent verifications to the same number are not allowed
# - value: '15'
# description: The request has been rejected.
# - value: '16'
# description: The code inserted does not match the expected value
# - value: '17'
# description: >-
# You can run Verify Check on a `request_id` up to three times
# unless a new PIN code is generated. If you check a request
# more than 3 times, it is set to FAILED and you cannot check it
# again.
# - value: '18'
# description: >-
# You added more than the maximum of 10 `request_id`s to your
# request.
# - value: '19'
# description: No more events are left to execute for the request
# - value: '101'
# description: There are no matching Verify requests.
error_text:
type: string
description: 'If `status` is non-zero, this explains the error encountered.'
example: error
xml:
name: verify_response
checkResponse:
type: object
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: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
example: aaaaaaaa-bbbb-...
event_id:
type: string
description: The `message-id` of the verification SMS.
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
error_text:
type: string
description: If the `status` is non-zero, this explains the error encountered.
example: error
xml:
name: verify_response
searchResponse:
xml:
name: verify_request
type: object
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: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
example: aaaaaaaa-bbbb-...
account_id:
type: string
description: The Nexmo account ID the request was for.
example: abcdef01
status:
type: string
# description: The status of the Verify request.
example: IN PROGRESS
enum:
- IN PROGRESS
- SUCCESS
- FAILED
- EXPIRED
- CANCELLED
- '101'
description: |
Code | Description
-- | --
IN PROGRESS | The search is still in progress.
SUCCESS | Your user entered a correct verification code.
FAILED | Your user entered an incorrect code more than three times.
EXPIRED | Your user did not enter a code before the `pin_expiry` time elapsed.
CANCELLED | The verification process was cancelled by a Verify control request.
101 | You supplied an invalid `request_id`.
# x-ms-enum:
# values:
# - value: IN PROGRESS
# description: still in progress.
# - value: SUCCESS
# description: your user entered the PIN correctly.
# - value: FAILED
# description: user entered the wrong pin more than 3 times.
# - value: EXPIRED
# description: no PIN entered during the `pin_expiry` time.
# - value: CANCELLED
# description: the request was cancelled using Verify Control.
# - value: '101'
# description: >-
# the `request_id` you set in the Verify Search request is
# invalid.
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
example: '2020-01-01 12:00:00'
code:
type: string
status:
type: string
enum:
- VALID
- INVALID
ip_address:
type: string
example: 123.0.0.255
error_text:
type: string
description: If `status` is not `SUCCESS`, this message explains the issue encountered.
example: user entered the wrong pin more than 3 times
controlResponse:
type: object
xml:
name: response
properties:
status:
type: string
example: '0'
enum:
- '0'
- '19'
description: |
`cmd` | Code | Description
-- | -- | --
Any | 0 | Success
`cancel` | 19 | 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.
`trigger_next_event` | 19 | All attempts to deliver the verification code for this request have completed and there are no remaining events to advance to.
# x-ms-enum:
# values:
# - value: '0'
# description: Success
# - value: null
# description: >-
# Cancel: You must wait at least 30s after sending a Verify
# Request before cancelling, or Verify has made too many
# attempts to redeliver a PIN for this request; you have to wait
# for the workflow to complete. Also, you cannot initiate a new
# Verify Request until this one expires. Trigger_next_event: All
# the attempts to deliver the PIN for this request have been
# completed and there are no more events to skip to.
command:
type: string
description: The `cmd` you sent in the request.
enum:
- cancel
- trigger_next_event
example: cancel
error_text:
type: string
description: If the `status` is non-zero, this explains the error encountered.
example: error
securitySchemes:
apiKey:
type: apiKey
name: api_key
in: query
description: >-
You can find your API key in your Nexmo account [developer
dashboard](https://dashboard.nexmo.com/)
apiSecret:
type: apiKey
name: api_secret
in: query
description: >-
You can find your API secret in your Nexmo account [developer
dashboard](https://dashboard.nexmo.com)