nexmo_api_specification 0.5.0 → 0.5.2

data/definitions/number-insight.yml

@@ -0,0 +1,685 @@
+---
+openapi: 3.0.0
+servers:
+  - url: 'https://api.nexmo.com/ni'
+info:
+  title: Nexmo Number Insight API
+  version: 1.0.0
+  description: >-
+    Nexmo's Number Insight API provides details about the validity, reachability and roaming status of a phone number, as well as giving you details on how to format the number properly in your application. There are three levels of Number Insight API available: Basic, Standard and Advanced. The advanced API is available asynchronously as well as synchronously. Getting information about a number with Nexmo's Number Insight API is easy. Simply [sign up for an account](https://dashboard.nexmo.com/sign-up).
+  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/number-insight
+  x-sha1: 081f6d985e2e4a75586da1654fde880a96885405
+security:
+  - apiKey: []
+    apiSecret: []
+tags:
+  - name: Request
+    description: 'Ask for information about a phone number'
+paths:
+  '/{level}/{format}':
+    parameters:
+      - $ref: '#/components/parameters/level'
+      - $ref: '#/components/parameters/format'
+    get:
+      operationId: getNumberInsight
+      summary: ask for information about a phone number
+      tags:
+        - Request
+      parameters:
+        - $ref: '#/components/parameters/number'
+        - $ref: '#/components/parameters/country'
+        - $ref: '#/components/parameters/cnam'
+        - $ref: '#/components/parameters/ip'
+      responses:
+        '200':
+          description: OK
+          content:
+            'application/json':
+              schema:
+                $ref: '#/components/schemas/niResponse'
+            'text/xml':
+              schema:
+                $ref: '#/components/schemas/niResponse'
+        '401':
+          description: Unauthorised
+  '/advanced/async/{format}':
+    parameters:
+      - $ref: '#/components/parameters/format'
+    get:
+      operationId: getNumberInsightAsync
+      summary: Ask for information about a phone number
+      tags:
+        - Request
+      parameters:
+        - $ref: '#/components/parameters/callback'
+        - $ref: '#/components/parameters/number'
+        - $ref: '#/components/parameters/country'
+        - $ref: '#/components/parameters/cnam'
+        - $ref: '#/components/parameters/ip'
+      responses:
+        '200':
+          description: OK
+          content:
+            'application/json':
+              schema:
+                $ref: '#/components/schemas/niResponse'
+            'text/xml':
+              schema:
+                $ref: '#/components/schemas/niResponse'
+        '401':
+          description: Unauthorised
+      callbacks:
+        onData:
+          '{$request.query.callback}':
+            post:
+              operationId: asyncCallback
+              summary: The requested WebHook response
+              requestBody:
+                description: Async response payload
+                content:
+                  application/json:
+                    schema:
+                      $ref: '#/components/schemas/niResponse'
+                  text/xml:
+                    schema:
+                      $ref: '#/components/schemas/niResponse'
+              responses:
+                '200':
+                  description: OK
+components:
+  parameters:
+    level:
+      name: level
+      in: path
+      required: true
+      description: 'The level of request you wish to make.'
+      schema:
+        type: string
+        enum:
+          - 'basic'
+          - 'standard'
+          - 'advanced'
+    format:
+      name: format
+      in: path
+      required: true
+      description: 'The format of the response'
+      schema:
+        type: string
+        enum:
+          - 'json'
+          - 'xml'
+    number:
+      name: number
+      in: query
+      description: 'A single phone number that you need insight about in national or international format.'
+      example: '447700900000'
+      schema:
+        type: string
+        pattern: '^[0-9-+\(\)\s]*$'
+    country:
+      name: country
+      in: query
+      example: 'GB'
+      description: 'If a number does not have a country code or is uncertain, set the two-character country code. This code must be in ISO 3166-1 alpha-2 format and in upper case. For example, GB or US. If you set country and number is already in [E.164](https://en.wikipedia.org/wiki/E.164) format, country must match the country code in number.'
+      schema:
+        type: string
+        pattern: '[A-Z]{2}'
+    cnam:
+      name: cnam
+      in: query
+      example: true
+      description: 'Indicates if the name of the person who owns the phone number should be looked up and returned in the response. Set to true to receive phone number owner name in the response. This features is available for US numbers only and incurs an additional charge.'
+      schema:
+        type: boolean
+        default: false
+    ip:
+      name: ip
+      in: query
+      example: '123.0.0.255'
+      description: "The IP address of the user. If supplied, we will compare this to the country the user's phone is located in and return an error if it does not match."
+      schema:
+        type: string
+        #pattern: TODO are IPv4 and IPv6 addresses permitted?
+    callback:
+      name: callback
+      in: query
+      example: 'https://example.com/callback'
+      description: 'The callback URL'
+      required: true
+      schema:
+        type: string
+        format: uriref
+  schemas:
+    niResponse:
+      oneOf:
+        - $ref: '#/components/schemas/niError'
+        - $ref: '#/components/schemas/niDetails'
+        - $ref: '#/components/schemas/format'
+        - $ref: '#/components/schemas/lookup'
+    niError:
+      type: object
+      properties:
+        status:
+          $ref: '#/components/schemas/niStatus'
+        error_text:
+          type: string
+      required:
+        - status
+        - error_text
+    format:
+      type: object
+      properties:
+        lookup_outcome:
+          type: object
+          properties:
+            code:
+              type: integer
+              description: |
+                Shows if all information about a phone number has been returned. Possible values:
+                Code | Text
+                -- | --
+                0 | Success
+                1 | Partial success - some fields populated
+                2 | Failed
+              enum:
+                - 0
+                - 1
+                - 2
+        lookup_outcome_message:
+          type: string
+          description: 'Shows if all information about a phone number has been returned.'
+          xml:
+            x-text: true # see https://github.com/OAI/OpenAPI-Specification/issues/630
+        reachable:
+          type: string
+          description: 'Can you call `number` now. This is applicable to mobile numbers only.'
+          enum:
+            - unknown
+            - reachable
+            - undeliverable
+            - absent
+            - bad_number
+            - blacklisted
+        request_id:
+          type: string
+          description: 'The unique identifier for your request. This is a alphanumeric string up to 40 characters.'
+          maxLength: 40
+        international_format_number:
+          type: string
+          description: 'The `number` in your request in International format.'
+        local_number:
+          type: object
+          properties:
+            country_code:
+              type: string
+              description: 'Two character country code for `number`. This is in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.'
+              pattern: '[A-Z]{2}'
+              xml:
+                attribute: true
+            country_code_iso3:
+              type: string
+              description: 'Three character country code for `number`. This is in [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) format.'
+              pattern: '[A-Z]{3}'
+              xml:
+                attribute: true
+            country_name:
+              type: string
+              description: 'The full name of the country that `number` is registered in.'
+              xml:
+                attribute: true
+            country_prefix:
+              type: string
+              description: 'The numeric prefix for the country that `number` is registered in.'
+              xml:
+                attribute: true
+            national_format_number:
+              type: string
+              description: 'The `number` in your request in the format used by the country the number belongs to.'
+              xml:
+                x-text: true # see https://github.com/OAI/OpenAPI-Specification/issues/630
+            error:
+              type: object
+              properties:
+                code:
+                  allOf:
+                    - xml:
+                        attribute: true
+                    - $ref: '#/components/schemas/niStatus'
+                status_message:
+                  type: string
+                  xml:
+                    x-text: true # see https://github.com/OAI/OpenAPI-Specification/issues/630
+    lookup:
+      type: object
+      properties:
+        request_id:
+          type: string
+          description: 'The unique identifier for your request. This is a alphanumeric string up to 40 characters.'
+          maxLength: 40
+        international_format_number:
+          type: string
+          description: 'The `number` in your request in International format.'
+        local_number:
+          type: object
+          properties:
+            country_code:
+              type: string
+              description: 'Two character country code for `number`. This is in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.'
+              pattern: '[A-Z]{2}'
+              xml:
+                attribute: true
+            country_code_iso3:
+              type: string
+              description: 'Three character country code for `number`. This is in [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) format.'
+              pattern: '[A-Z]{3}'
+              xml:
+                attribute: true
+            country_name:
+              type: string
+              description: 'The full name of the country that `number` is registered in.'
+              xml:
+                attribute: true
+            country_prefix:
+              type: string
+              description: 'The numeric prefix for the country that `number` is registered in.'
+              xml:
+                attribute: true
+            national_format_number:
+              type: string
+              description: 'The `number` in your request in the format used by the country the number belongs to.'
+              xml:
+                x-text: true # see https://github.com/OAI/OpenAPI-Specification/issues/630
+        error:
+          type: object
+          properties:
+            code:
+              allOf:
+                - xml:
+                    attribute: true
+                - $ref: '#/components/schemas/niStatus'
+            status_message:
+              type: string
+              xml:
+                x-text: true # see https://github.com/OAI/OpenAPI-Specification/issues/630
+        request_price:
+          type: number
+          description: 'The amount in EUR charged to your account.'
+        refund_price:
+          type: number
+          description: 'If there is an internal lookup error, the `refund_price` will reflect the lookup price. If `cnam` is requested for a non-US number the `refund_price` will reflect the `cnam` price. If both of these conditions occur, `refund_price` is the sum of the lookup price and `cnam` price.'
+        remaining_balance:
+          type: number
+          description: 'Your account balance in EUR after this request. Not returned with Number Insight Advanced Async API.'
+        current_carrier:
+          description: 'Information about the network `number` is currently connected to.'
+          $ref: '#/components/schemas/niCarrier'
+        original_carrier:
+          description: 'Information about the network `number` was initially connected to.'
+          $ref: '#/components/schemas/niCarrier'
+        ported:
+          type: string
+          description: 'If the user has changed carrier for `number`. The assumed status means that the information supplier has replied to the request but has not said explicitly that the number is ported.'
+          enum:
+            - unknown
+            - ported
+            - not_ported
+            - assumed_not_ported
+            - assumed_ported
+        caller_name:
+          type: string
+          description: 'Full name of the person who owns the phone number. `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.'
+        last_name:
+          type: string
+          description: 'Last name of the person who owns the phone number if the owner is an individual. This parameter is only present if `cnam` had a value of `true` within the request.'
+        first_name:
+          type: string
+          description: 'First name of the person who owns the phone number if the owner is an individual. This parameter is only present if `cnam` had a value of `true` within the request.'
+        caller_type:
+          type: string
+          description: 'The value will be `business` if the owner of a phone number is a business. If the owner is an individual the value will be `consumer`. The value will be `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.'
+          enum:
+            - business
+            - consumer
+            - unknown
+        roaming:
+          description: 'Information about the roaming status for `number`. This is applicable to mobile numbers only.'
+          $ref: '#/components/schemas/niRoaming'
+        ip:
+          type: string
+          description: 'The ip address you specified in the request. This field is blank if you did not specify `ip`.'
+        ip_warnings:
+          type: string
+          description: 'Warning levels for `ip`: `unknown` or `no_warning`'
+          enum:
+            - unknown
+            - no_warning
+        ip_match_level:
+          type: string
+          description: 'The match status between ip and number parameters. This value is only returned if you set ip in the `request`.'
+          enum:
+            - 'Country Level'
+            - 'Mismatch'
+        ip_country:
+          type: string
+          description: 'The country that `ip` is allocated to. This value is only returned if you set ip in the `request`.'
+    niDetails:
+      type: object
+      properties:
+        status:
+          $ref: '#/components/schemas/niStatus'
+        status_message:
+          type: string
+          description: 'The status description of your request.'
+          example: 'Success'
+        lookup_outcome:
+          type: integer
+          description: |
+            Shows if all information about a phone number has been returned. Possible values:
+            Code | Text
+            -- | --
+            0 | Success
+            1 | Partial success - some fields populated
+            2 | Failed
+          enum:
+            - 0
+            - 1
+            - 2
+          example: '0'
+        lookup_outcome_message:
+          type: string
+          description: 'Shows if all information about a phone number has been returned.'
+          example: 'Success'
+        request_id:
+          type: string
+          description: 'The unique identifier for your request. This is a alphanumeric string up to 40 characters.'
+          example: 'aaaaaaaa-bbbb-cccc-dddd-0123456789ab'
+          maxLength: 40
+        international_format_number:
+          type: string
+          description: "The `number` in your request in international format."
+          example: "447700900000"
+        national_format_number:
+          type: string
+          description: "The `number` in your request in the format used by the country the number belongs to."
+          example: "07700 900000"
+        country_code:
+          type: string
+          description: 'Two character country code for `number`. This is in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.'
+          example: "GB"
+          pattern: '[A-Z]{2}'
+        country_code_iso3:
+          type: string
+          description: 'Three character country code for `number`. This is in [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) format.'
+          example: "GBR"
+          pattern: '[A-Z]{3}'
+        country_name:
+          type: string
+          description: 'The full name of the country that `number` is registered in.'
+          example: "United Kingdom"
+        country_prefix:
+          type: string
+          description: 'The numeric prefix for the country that `number` is registered in.'
+          example: '44'
+        request_price:
+          type: number
+          description: 'The amount in EUR charged to your account.'
+          example: "0.04000000"
+        refund_price:
+          type: number
+          description: 'If there is an internal lookup error, the `refund_price` will reflect the lookup price. If `cnam` is requested for a non-US number the `refund_price` will reflect the `cnam` price. If both of these conditions occur, `refund_price` is the sum of the lookup price and `cnam` price.'
+          example: '0.01'
+        remaining_balance:
+          type: number
+          description: 'Your account balance in EUR after this request. Not returned with Number Insight Advanced Async API.'
+          example: '1.23456789'
+        current_carrier:
+          description: 'Information about the network `number` is currently connected to.'
+          $ref: '#/components/schemas/niCarrier'
+        original_carrier:
+          description: 'Information about the network `number` was initially connected to.'
+          $ref: '#/components/schemas/niCarrier'
+        valid_number:
+          type: string
+          description: 'Does `number` exist. This is applicable to mobile numbers only.'
+          enum:
+            - unknown
+            - valid
+            - not_valid
+          example: 'valid'
+        reachable:
+          type: string
+          description: 'Can you call `number` now. This is applicable to mobile numbers only.'
+          enum:
+            - unknown
+            - reachable
+            - undeliverable
+            - absent
+            - bad_number
+            - blacklisted
+          example: 'reachable'
+        ported:
+          type: string
+          description: 'If the user has changed carrier for `number`. The assumed status means that the information supplier has replied to the request but has not said explicitly that the number is ported.'
+          enum:
+            - unknown
+            - ported
+            - not_ported
+            - assumed_not_ported
+            - assumed_ported
+          example:
+            - 'not_ported'
+        roaming:
+          description: 'Information about the roaming status for `number`. This is applicable to mobile numbers only.'
+          $ref: '#/components/schemas/niRoaming'
+        ip:
+          description: 'Information about the provided IP address'
+          $ref: '#/components/schemas/niIP'
+        ip_warnings:
+          type: string
+          description: 'Warning levels for `ip`'
+          enum:
+            - unknown
+            - no_warning
+          example: 'no_warning'
+        caller_identity:
+          description: 'Information about the roaming status for `number`. This is applicable to mobile numbers only.'
+          $ref: '#/components/schemas/niCallerIdentity'
+        # END
+        caller_name:
+          type: string
+          description: 'Full name of the person who owns the phone number. `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.'
+          example: 'John Smith'
+        last_name:
+          type: string
+          description: 'Last name of the person who owns the phone number if the owner is an individual. This parameter is only present if `cnam` had a value of `true` within the request.'
+          example: 'Smith'
+        first_name:
+          type: string
+          description: 'First name of the person who owns the phone number if the owner is an individual. This parameter is only present if `cnam` had a value of `true` within the request.'
+          example: 'John'
+        caller_type:
+          type: string
+          description: 'The value will be `business` if the owner of a phone number is a business. If the owner is an individual the value will be `consumer`. The value will be `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.'
+          enum:
+            - business
+            - consumer
+            - unknown
+          example: 'consumer'
+      required:
+        - status
+        - status_message
+        - request_id
+        - international_format_number
+        - national_format_number
+        - country_code
+        - country_code_iso3
+        - country_name
+        - country_prefix
+    niStatus:
+      type: integer
+      enum:
+        - 0
+        - 1
+        - 3
+        - 4
+        - 5
+        - 9
+        - 19
+        - 43
+        - 44
+        - 45
+        - 999
+      description: |
+        Code | Text
+        -- | --
+        0 | Success - request accepted for delivery by Nexmo.
+        1 | Busy - you have made more requests in the last second than are permitted by your Nexmo account. Please retry.
+        3 | Invalid - your request is incomplete and missing some mandatory parameters.
+        4 | Invalid credentials - the _api_key_ or _api_secret_ you supplied is either not valid or has been disabled.
+        5 | Internal Error - the format of the recipient address is not valid.
+        9 | Partner quota exceeded - your Nexmo account does not have sufficient credit to process this request.
+
+        ## Standard and Advanced only
+
+        Code | Text
+        -- | --
+        19 | Facility Not Allowed - your request makes use of a facility that is not enabled on your account.
+        43, 44, 45 | Live mobile lookup not returned. Not all return parameters are available.
+        999 | Request unparseable.
+    niCarrier:
+      type: object
+      properties:
+        network_code:
+          type: string
+          description: 'The [https://en.wikipedia.org/wiki/Mobile_country_code](https://en.wikipedia.org/wiki/Mobile_country_code) for the carrier`number` is associated with. Unreal numbers are marked as`unknown` and the request is rejected altogether if the number is impossible according to the [E.164](https://en.wikipedia.org/wiki/E.164) guidelines.'
+          xml:
+            attribute: true
+          example: '12345'
+        name:
+          type: string
+          description: 'The full name of the carrier that `number` is associated with.'
+          xml:
+            attribute: true
+          example: 'Acme Inc'
+        country:
+          type: string
+          description: 'The country that `number` is associated with. This is in ISO 3166-1 alpha-2 format.'
+          xml:
+            attribute: true
+          example: 'GB'
+        network_type:
+          type: string
+          description: 'The type of network that `number` is associated with.'
+          enum:
+            - mobile
+            - landline
+            - landline_premium
+            - landline_tollfree
+            - virtual
+            - unknown
+            - pager
+          xml:
+            attribute: true
+          example: 'mobile'
+    niRoaming:
+      type: object
+      properties:
+        status:
+            type: string
+            description: 'Is `number` outside its home carrier network.'
+            enum:
+              - unknown
+              - roaming
+              - not_roaming
+            xml:
+              attribute: true
+        roaming_country_code:
+            type: string
+            description: 'If `number` is `roaming`, this is the [code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the country `number` is roaming in.'
+            xml:
+              attribute: true
+        roaming_network_code:
+            type: string
+            description: 'If `number` is `roaming`, this is the id of the carrier network `number` is roaming in.'
+            xml:
+              attribute: true
+        roaming_network_name:
+            type: string
+            description: 'If `number` is `roaming`, this is the name of the carrier network `number` is roaming in.'
+            xml:
+              attribute: true
+    niIP:
+      type: object
+      properties:
+        address:
+          type: string
+          description: 'The ip address you specified in the request.'
+          example: '123.0.0.255'
+        ip_match_level:
+          type: string
+          description: 'The match status between ip and number parameters.'
+          enum:
+            - 'country'
+            - 'mismatch'
+          example: 'country'
+        ip_country:
+          type: string
+          description: 'The country that `ip` is allocated to.'
+          example: 'GB'
+        ip_city:
+          type: string
+          description: 'The city that `ip` is allocated to.'
+          example: 'London'
+    niCallerIdentity:
+      type: object
+      properties:
+        caller_type:
+          type: string
+          description: 'The value will be `business` if the owner of a phone number is a business. If the owner is an individual the value will be `consumer`. The value will be `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.'
+          enum:
+            - business
+            - consumer
+            - unknown
+          example: 'consumer'
+        caller_name:
+          type: string
+          description: 'Full name of the person who owns the phone number. `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.'
+          example: 'John Smith'
+        first_name:
+          type: string
+          description: 'First name of the person who owns the phone number if the owner is an individual. This parameter is only present if `cnam` had a value of `true` within the request.'
+          example: 'John'
+        last_name:
+          type: string
+          description: 'Last name of the person who owns the phone number if the owner is an individual. This parameter is only present if `cnam` had a value of `true` within the request.'
+          example: 'Smith'
+        subscription_type:
+          type: string
+          # @TODO: description: ''
+          example: 'unknown'
+
+  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)'

data/definitions/sms.yml

@@ -169,6 +169,10 @@ components:
           description: '**Advanced**: The availability for an SMS in milliseconds. Depends on `type` parameter having the value `wappush`.'
           type: string
           example: https://example.com
+        client-ref:
+          description: '**Advanced**: You can optionally include your own reference of up to 40 characters.'
+          type: string
+          example: my-personal-reference'
     Error:
       type: object
       properties: