nexmo_api_specification 0.5.0 → 0.5.2

data/definitions/verify.yml

@@ -0,0 +1,737 @@
+openapi: 3.0.0
+servers:
+  - url: 'https://api.nexmo.com/verify'
+info:
+  title: Nexmo Verify API
+  version: 1.0.0
+  description: >-
+    Nexmo's Verify API allows you to send a PIN by SMS and phone to prove a user
+    can be contacted at a specific phone number.
+
+
+    This is useful for:
+
+
+    * Spam protection - prevent spammers from mass-creating new accounts (etc.)
+
+    * Hack protection - if you detect suspicious or significant activities,
+    validate that the person using a phone number owns it
+
+    * Two-factor authentication
+
+    * Reaching users - ensuring you have the correct phone number makes it easy
+    to contact users when you need to
+
+
+    By default, the PIN is first sent via text message (SMS). If there is no
+    reply the Verify API will then try a voice call using text-to-speech (TTS).
+
+
+    TTS messages are read in the locale that matches the phone number. (For
+    example, the TTS for a 61* phone number is sent using an Australian accent
+    for the English language (en-au). You can explicitly control the language,
+    accent and gender in TTS from the Verify Request.)
+  contact:
+    name: Nexmo.com
+    email: devrel@nexmo.com
+    url: 'https://developer.nexmo.com/'
+    x-twitter: Nexmo
+  termsOfService: 'https://www.nexmo.com/terms-of-use'
+  license:
+    name: The MIT License (MIT)
+    url: 'https://opensource.org/licenses/MIT'
+  x-logo:
+    url: 'https://twitter.com/Nexmo/profile_image?size=original'
+  x-apiClientRegistration: 'https://dashboard.nexmo.com/sign-up'
+externalDocs:
+  url: 'https://developer.nexmo.com/api/verify'
+  x-sha1: 481de32ea146584aabec4b76f62a86661f383078
+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:
+
+        * Create a Request to send a PIN to your user.
+
+        * Check the response codes in the Response to ensure that your request
+        was successful.
+      operationId: verifyRequest
+      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 set `number` in international format or you are not
+            sure if `number` is correctly formatted, set `country` with the
+            two-character country code. Verify works out the international phone
+            number for you.
+          schema:
+            type: string
+          example: GB
+        - name: brand
+          required: true
+          in: query
+          description: >-
+            The name of the company or App you are using Verify for. This 18
+            character alphanumeric string is used in the body of Verify message.
+            For example: "Your _brand_ PIN is ...".
+          schema:
+            type: string
+            maxLength: 18
+          example: Acme Inc
+        - name: sender_id
+          required: false
+          in: query
+          description: >-
+            An 11 character alphanumeric string to specify the SenderID for SMS
+            sent by Verify. Depending on the destination of the phone number you
+            are applying, restrictions may apply.
+          schema:
+            type: string
+            maxLength: 11
+            default: VERIFY
+          example: VERIFY
+        - name: code_length
+          required: false
+          in: query
+          description: The length of the PIN.
+          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.
+
+            **Note**: contact [support@nexmo.com](mailto:support@nexmo.com) to
+            enable this feature.
+          schema:
+            type: string
+            enum:
+              - All
+              - Mobile
+              - Landline
+          example: All
+        - name: pin_expiry
+          required: false
+          in: query
+          description: >-
+            The PIN validity time from generation, in seconds. When specified
+            together, pin_expiry must be an integer multiple of
+            `next_event_wait`. Otherwise, pin_expiry is set to equal
+            next_event_wait. For example:
+
+
+            *   `pin_expiry` = 360 seconds, so `next_event_wait` = 120 seconds -
+            all three attempts have the same PIN.
+
+            *   `pin_expiry` = 240 seconds, so `next_event_wait` = 120 seconds -
+            1st and 2nd attempts have the same PIN, third attempt has a
+            different PIN.
+
+            *   `pin_expiry` = 120 (or 200 or 400 seconds) - each attempt has a
+            different PIN.
+          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
+            PIN. Verify calculates the default value based on the average time
+            taken by users to complete verification.
+          schema:
+            type: integer
+            minimum: 60
+            maximum: 900
+          example: 300
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/requestResponse'
+            text/plain:
+              schema:
+                $ref: '#/components/schemas/requestResponse'
+  '/check/{format}':
+    get:
+      description: >-
+        To use Verify Check you:
+
+
+        * Use a check request to send the PIN you received from your user to
+        Nexmo.
+
+        * Check the response codes in the response to see if the PIN sent by
+        your user matched the PIN generated by Nexmo.
+      operationId: verifyCheck
+      tags:
+        - Verify Check
+      parameters:
+        - $ref: '#/components/parameters/format'
+        - name: request_id
+          required: true
+          in: query
+          description: >-
+            The identifier of the Verify request to check. This is the
+            `request_id` you received in the Verify Request response.
+          schema:
+            type: string
+            maxLength: 32
+          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
+        - name: code
+          required: true
+          in: query
+          description: The PIN given 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 PIN. Nexmo
+            uses this information to identify fraud and spam patterns across our
+            customer base. 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/plain:
+              schema:
+                $ref: '#/components/schemas/checkResponse'
+  '/search/{format}':
+    get:
+      description: >-
+        1. Send a Verify Search request containing the `request_id`s of the
+        Verify requests to search for.
+
+        2. Check the `status` response parameter in the Search Response to see
+        if the request was successfully completed.
+      operationId: verifySearch
+      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
+        - 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
+            maxItems: 10
+          style: form
+          explode: true
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/searchResponse'
+            text/plain:
+              schema:
+                $ref: '#/components/schemas/searchResponse'
+  '/control/{format}':
+    get:
+      description: |-
+        To control the progress of your Verify Requests:
+
+        1. Send a Verify request.
+        2. Check the response.
+      operationId: verifyControl
+      tags:
+        - Verify Control
+      parameters:
+        - $ref: '#/components/parameters/format'
+        - name: request_id
+          required: true
+          in: query
+          description: 'The `request_id` you received in the Verify Request Response].'
+          schema:
+            type: string
+          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
+        - name: cmd
+          required: true
+          in: query
+          description: >-
+            Change the command workflow. Verification requests can't be
+            cancelled within the first 30 seconds. You must wait at least 30s
+            after sending a Verify Request before cancelling.
+          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/plain:
+              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 sent. You use this
+            request_id for the Verify Check.
+          maxLength: 32
+          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
+        status:
+          type: string
+          description: The response code that explains how your request proceeded.
+          example: '0'
+          enum:
+            - '0'
+            - '1'
+            - '2'
+            - '3'
+            - '4'
+            - '5'
+            - '6'
+            - '7'
+            - '8'
+            - '9'
+            - '10'
+            - '15'
+            - '16'
+            - '17'
+            - '18'
+            - '19'
+            - '101'
+          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 not 0, this explains the error encountered.'
+          example: error
+      xml:
+        name: verify_response
+    checkResponse:
+      type: object
+      properties:
+        request_id:
+          type: string
+          description: >-
+            The `request_id` you received in the Verify Request Response and
+            used in the Verify Search request.
+          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
+        event_id:
+          type: string
+          description: The identifier of the SMS `message-id`.
+          example: 0A00000012345678
+        status:
+          type: string
+          description: >-
+            If the value of status is `0`, your user entered the correct PIN. If
+            it is not, check the response code.
+          example: '0'
+        price:
+          type: string
+          description: The price charged for this Verify request.
+          example: '0.10000000'
+        currency:
+          type: string
+          description: Currency code.
+          example: EUR
+        error_text:
+          type: string
+          description: 'If status is not 0, this is brief explanation about the error.'
+          example: error
+      xml:
+        name: verify_response
+    searchResponse:
+      xml:
+        name: verify_request
+      type: object
+      properties:
+        request_id:
+          type: string
+          description: >-
+            The `request_id` you received in the Verify Request Response and
+            used in the Verify Search request.
+          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
+        account_id:
+          type: string
+          description: The 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'
+          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 _Verify Request_ was made for.
+          example: '447700900000'
+        price:
+          type: string
+          description: The price charged for this _Verify 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. This
+            response parameter is 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: >-
+            Time first attempt was made. This response parameter is in the
+            following format YYYY-MM-DD HH:MM:SS.
+          example: '2020-01-01 12:00:00'
+        last_event_date:
+          type: string
+          description: >-
+            Time last attempt was made. This response parameter is 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.'
+          example: user entered the wrong pin more than 3 times
+    controlResponse:
+      type: object
+      xml:
+        name: response
+      properties:
+        status:
+          type: string
+          description: >-
+            The Verify Control Response code that explains how your request
+            proceeded.
+          example: '0'
+          enum:
+            - '0'
+            - '19'
+          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.
+          example: cancel
+        error_text:
+          type: string
+          description: 'If status is not 0, 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 [account
+        overview](https://dashboard.nexmo.com/account-overview)
+    apiSecret:
+      type: apiKey
+      name: api_secret
+      in: query
+      description: >-
+        You can find your API secret in your [account
+        overview](https://dashboard.nexmo.com/account-overview)