swagger: '2.0'
info:
  title: Number Insight - Vonage
  version: "v1.1.1"
  termsOfService: 'https://developer.kpn.com/legal'
  contact:
    name: API Support
    email: api_developer@kpn.com
    url: 'https://developer.kpn.com/support'
  description: >-
    Vonage'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 the
    Number Insight API available:
       - Basic
       - Standard
       - Advanced
       
      The advanced API is available asynchronously as well as synchronously.

    ## [Source view](https://app.swaggerhub.com/apis/kpn/number-insight-nexmo/)<br/>
    [Documentation view](https://app.swaggerhub.com/apis-docs/kpn/number-insight-nexmo/)
    
    ---
    
    ## [KPN Developer](https://developer.kpn.com/)<br/>
    [Getting Started](https://developer.kpn.com/getting-started)
    
    ---

host: api-prd.kpn.com
basePath: /communication/nexmo/number-insight
externalDocs:
  description: HTTP response headers
  url: https://developer.kpn.com/documentation-response-headers
schemes:
  - https
paths:
  '/{level}':
    post:
      summary: Synchronously get information about a phone number
      operationId: NumberInsight
      tags:
        - Request
      description: >-
        **Number Insight Basic**
        
        You can use Vonage's Number Insight Basic API to retrieve local and
        international representations of a phone number by doing semantic checks
        on the number you submit. This can help you normalise and consistently
        print numbers in your user interface and gives you information to help
        you decide if a phone number accept the phone number entered by your
        user, or ask them to check and correct it.

          Number Insight Basic API is a free synchronous, easy-to-use RESTful web service. For any phone number you can
          
           - Retrieve the international and local format.
           - Know the country where the number is registered.
         
        ### Example
          
          Request:
          
          ```
          curl -X POST \
            https://api-prd.kpn.com/communication/nexmo/number-insight/basic \
            -H 'authorization: Bearer ZvV84AtjcXoHU48hA6b5AZljegdy' \
            -H 'content-type: application/x-www-form-urlencoded' \
            -d 'number=447700900000'

          ```
          
          Response:
          
          ```
          {
              "status": 0,
              "status_message": "Success",
              "request_id": "fcb1e9a2-db9c-4ea2-84be-4e60da45e187",
              "international_format_number": "447700900000",
              "national_format_number": "07700 900000",
              "country_code": "GB",
              "country_code_iso3": "GBR",
              "country_name": "United Kingdom",
              "country_prefix": "44"
          }
          
          ```
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - application
      parameters:
        - in: path
          name: level
          description: >-
            The level of request you wish to make.
          enum: ['basic','standard','advanced']    
          required: true
          type: string
        - in: formData
          name: number
          description: >- 
            The single phone number that you need insight about in national or international format.
                example: 447700900000
          pattern: '^[0-9-+\(\)\s]*$'
          required: true
          type: string
        - in: formData
          name: country
          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.
              example: GB
          pattern: '[A-Z]{2}'
          required: false
          type: string  
        - in: formData
          name: cnam
          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.
              example: true
          required: false
          type: boolean    
        - in: formData
          name: ip
          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.
              example: 123.0.0.255
          required: false
          type: string          
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/niResponseBasic'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '429':
          description: Too Many Requests
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - OAuth2: []
  '/advanced/async':
    post:
      summary: Asynchronously get information about a phone number
      tags:
        - Request
      description: |-
        **Number Insight Advanced Async**
        You can use Vonage's Number Insight Async API to retrieve a user's landline or mobile number, including checking to see that it is registered to an operator. This can help you verify that a phone number is real and give you information on how to format the number.
        
        Number Insight Advanced Async API is an asynchronous web service that returns data to a webhook. For any phone number you can
        
        - Retrieve the international and local format.
        - Know the country where the number is registered.
        - Line type detection (mobile/landline/virtual number/premium/toll-free)
        - Detect mobile country code (MCC) and mobile network code (MNC)
        - Detect if number is ported
        - Identify caller name (USA only)
        - Identify network when roaming
        - Confirm user's IP address is in same location as their mobile phone

        Users are advised that the Advanced API does not give any information about landlines that is not already given by the Standard API. For number insights about landlines, you should use the Standard API.

         ### Example
          
          Request:
          
          ```
          curl -X POST \
            https://api-prd.kpn.com/communication/nexmo/number-insight/advanced/async \
            -H 'authorization: Bearer ZvV84AtjcXoHU48hA6b5AZljegdy' \
            -H 'content-type: application/x-www-form-urlencoded' \
            -d 'number=31620028461'
            -d 'callback=https://example.com/callback'
          
          ```
          
          Response:
          
          ```
          {
              "request_id": "c510011c-d782-4f49-bfa9-38a2254884e4",
              "number": "447700900000",
              "remaining_balance": "10.000000",
              "request_price": "0.03000000",
              "status": 0
          }
          ```        
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - application
      parameters:
        - in: formData
          name: number
          description: >- 
            The single phone number that you need insight about in national or international format.
                example: 447700900000
          pattern: '^[0-9-+\(\)\s]*$'
          required: true
          type: string
        - in: formData
          name: callback
          description: >- 
            The callback URL
              example: https://example.com/callback
          required: true
          type: string            
        - in: formData
          name: country
          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.
              example: GB
          pattern: '[A-Z]{2}'
          required: false
          type: string  
        - in: formData
          name: cnam
          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.
              example: true
          required: false
          type: boolean    
        - in: formData
          name: ip
          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.
              example: 123.0.0.255
          required: false
          type: string         
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/niResponseAsync'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '429':
          description: Too Many Requests
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - OAuth2: []
securityDefinitions:
  OAuth2:
    type: oauth2
    tokenUrl: >-
      https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials
    flow: application
definitions:
  niResponseBasic:
      type: object
      description: Basic
      properties:
        status:
          $ref: '#/definitions/niStatus'
        status_message:
          type: string
          description: 'The status description of your request.'
          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'
  niResponseStandard:
      type: object
      description: Standard
      properties:
        status:
          $ref: '#/definitions/niStatus'
        status_message:
          type: string
          description: 'The status description of your request.'
          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.01500000'
        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:
          $ref: '#/definitions/niCarrier'
        original_carrier:
          $ref: '#/definitions/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
          example: 'not_ported'
        roaming:
          $ref: '#/definitions/niRoaming'
        caller_identity:
          $ref: '#/definitions/niCallerIdentity'
        caller_name:
          type: string
          description: 'Full name of the person or business 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'
  niResponseAdvanced:
      type: object
      description: Advanced
      properties:
        status:
          $ref: '#/definitions/niStatus'
        status_message:
          type: string
          description: 'The status description of your request.'
          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.01500000'
        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:
          $ref: '#/definitions/niCarrier'
        original_carrier:
          $ref: '#/definitions/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
          example: 'not_ported'
        roaming:
          $ref: '#/definitions/niRoaming'
        caller_identity:
          $ref: '#/definitions/niCallerIdentity'
        caller_name:
          type: string
          description: 'Full name of the person or business 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'
        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'
        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'
        ip:
          $ref: '#/definitions/niIP'
        ip_warnings:
          type: string
          description: 'Warning levels for `ip`'
          enum:
            - unknown
            - no_warning
          example: 'no_warning'
      required:
        - status
        - status_message
        - request_id
        - international_format_number
        - national_format_number
        - country_code
        - country_code_iso3
        - country_name
        - country_prefix
  niCarrier:
      type: object
      description: 'Information about the network `number` was initially connected to.'      
      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.'
          example: '12345'
        name:
          type: string
          description: 'The full name of the carrier that `number` is associated with.'
          example: 'Acme Inc'
        country:
          type: string
          description: 'The country that `number` is associated with. This is in ISO 3166-1 alpha-2 format.'
          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
          example: 'mobile'
  niRoaming:
      type: object
      description: 'Information about the network `number` is currently connected to.'
      properties:
        status:
            type: string
            description: 'Is `number` outside its home carrier network.'
            enum:
              - unknown
              - roaming
              - not_roaming
            example: roaming
        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.'
            example: US
        roaming_network_code:
            type: string
            description: 'If `number` is `roaming`, this is the id of the carrier network `number` is roaming in.'
            example: 12345
        roaming_network_name:
            type: string
            description: 'If `number` is `roaming`, this is the name of the carrier network `number` is roaming in.'
            example: 'Acme Inc'
  niIP:
      type: object
      description: 'Information about the provided IP address'      
      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
      description: 'Information about the network `number` is currently connected to.'      
      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 or business 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'
  niStatus:
      type: integer
      example: 0
      enum:
        - 0
        - 1
        - 3
        - 4
        - 5
        - 9
        - 19
        - 43
        - 44
        - 45
        - 999
      description: |
        Code | Text
        -- | --
        0 | Success - request accepted for delivery by Vonage.
        1 | Busy - you have made more requests in the last second than are permitted by your Vonage 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 Vonage 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. 
  niResponseAsync:
      type: object
      properties:
        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
        number:
          type: string
          description: "The `number` in your request"
          example: '447700900000'
        remaining_balance:
          type: string
          description: 'Your account balance in EUR after this request. Not returned with Number Insight Advanced Async API.'
          example: '1.23456789'
        request_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.01500000'
        status:
          $ref: '#/definitions/niStatus'        
  ErrorResponse:
    type: object
    properties:
      transactionId:
        type: string
        description: transaction id of the the request
        title: Transaction ID
      status:
        type: string
        description: Status
        title: Status
      name:
        type: string
        description: Error name
        title: Error name
      message:
        type: string
        description: Error message
        title: Error message
      info:
        type: string
        description: Additional information about error
        title: Info