---
openapi: 3.0.0
servers:
  - url: "https://api.nexmo.com/ni"
info:
  x-ballerina-display:
    label: Vonage Number Insight
    iconPath: "icon.png"
  title: Number Insight API
  version: 1.0.10
  description: >
    This is a generated connector for [Vonage Number Insight API v1.0.10](https://nexmo-api-specification.herokuapp.com/number-insight) OpenAPI specification. 

    The Number Insight API delivers real-time intelligence about the validity, reachability and roaming status of a phone number and tells you how to format the number correctly in your application. 
    
    There are three levels of Number Insight API available: [Basic, Standard and Advanced](https://developer.nexmo.com/number-insight/overview#basic-standard-and-advanced-apis). The advanced API is available asynchronously as well as synchronously.

    More Number Insight API documentation is at https://developer.nexmo.com/number-insight/overview#number-insight-api-overview.
  x-ballerina-init-description: >
    The connector initialization requires setting the API credentials. 
  
    Create a [Vonage account](https://www.vonage.com/) and obtain tokens by following [this guide](https://developer.nexmo.com/concepts/guides/authentication).
  contact:
    name: Vonage DevRel
    email: devrel@vonage.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/number-insight
  x-sha1: 081f6d985e2e4a75586da1654fde880a96885405
security:
  - apiKey: []
    apiSecret: []
paths:
  "/basic/{format}":
    parameters:
      - $ref: "#/components/parameters/format"
    get:
      operationId: getNumberInsightBasic
      summary: Basic Number Insight
      description: |
        Provides [basic number insight](/number-insight/overview#basic-standard-and-advanced-apis) information about a number.

        Note that this endpoint also supports `POST` requests.
      parameters:
        - $ref: "#/components/parameters/number"
        - $ref: "#/components/parameters/country"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/niResponseJsonBasic"
            text/xml:
              schema:
                $ref: "#/components/schemas/niResponseXmlBasic"
  "/standard/{format}":
    parameters:
      - $ref: "#/components/parameters/format"
    get:
      operationId: getNumberInsightStandard
      summary: Standard Number Insight
      description: |
        Provides [standard number insight](/number-insight/overview#basic-standard-and-advanced-apis) information about a number.

        Note that this endpoint also supports `POST` requests.
      parameters:
        - $ref: "#/components/parameters/number"
        - $ref: "#/components/parameters/country"
        - $ref: "#/components/parameters/cnam"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/niResponseJsonStandard"
            text/xml:
              schema:
                $ref: "#/components/schemas/niResponseXmlStandard"
  "/advanced/async/{format}":
    parameters:
      - $ref: "#/components/parameters/format"
    get:
      operationId: getNumberInsightAsync
      summary: Advanced Number Insight (async)
      description: |
        Provides [advanced number insight](/number-insight/overview#basic-standard-and-advanced-apis) number information **asynchronously** using the URL specified in the `callback` parameter.  recommends asynchronous use of the Number Insight Advanced API, to avoid timeouts.

        Note that this endpoint also supports `POST` requests.
      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/niResponseAsync"
            text/xml:
              schema:
                $ref: "#/components/schemas/niResponseAsync"
      callbacks:
        onData:
          "{$request.query.callback}":
            post:
              operationId: asyncCallback
              summary: Asynchronous response
              description: Contains the response to your Number Insight Advanced API request.
              requestBody:
                content:
                  application/json:
                    schema:
                      $ref: "#/components/schemas/niResponseJsonAdvanced"
                  text/xml:
                    schema:
                      $ref: "#/components/schemas/niResponseXmlAdvanced"
              responses:
                "200":
                  description: OK
  "/advanced/{format}":
    parameters:
      - $ref: "#/components/parameters/format"
    get:
      operationId: getNumberInsightAdvanced
      summary: Advanced Number Insight (sync)
      description: |
        Provides [advanced number insight](/number-insight/overview#basic-standard-and-advanced-apis) information about a number synchronously, in the same way that the basic and standard endpoints do.

        Vonage recommends accessing the Advanced API **asynchronously** using the `/advanced/async` endpoint, to avoid timeouts.

        Note that this endpoint also supports `POST` requests.
      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/niResponseJsonAdvanced"
            text/xml:
              schema:
                $ref: "#/components/schemas/niResponseXmlAdvanced"
components:
  parameters:
    format:
      name: format
      in: path
      required: true
      description: "The format of the response"
      example: json
      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"
      required: true
      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: "This parameter is deprecated as we are no longer able to retrieve reliable IP data globally from carriers. "
      x-ballerina-deprecated-reason: "This parameter is deprecated as we are no longer able to retrieve reliable IP data globally from carriers. "
      schema:
        type: string
      deprecated: true
    callback:
      name: callback
      in: query
      example: "https://example.com/callback"
      description: "The callback URL"
      required: true
      schema:
        type: string
        format: uriref

  schemas:
    niResponseAsync:
      type: object
      xml:
        name: lookup
      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
          xml:
            name: requestId
        number:
          type: string
          description: "The `number` in your request"
          example: "447700900000"
        remaining_balance:
          type: string
          description: "Your account balance in EUR after this request."
          example: "1.23456789"
          xml:
            name: remainingBalance
        request_price:
          type: string
          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"
          xml:
            name: requestPrice
        status:
          $ref: "#/components/schemas/niStandardAdvancedStatus"
        error_text:
          type: string
          description: "The status description of your request. Note: This field is equivalent to `status_message` field in the other endpoints"
          example: "Success"

    niResponseXmlBasic:
      type: object
      description: Basic
      xml:
        name: format
      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
          xml:
            name: request_id
        international_format_number:
          type: string
          description: "The `number` in your request in international format."
          example: "447700900000"
        local_number:
          type: object
          description: "An object containing the `number` in your request in the format used by the country the number belongs to."
          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."
              example: "GB"
              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."
              example: "GBR"
              pattern: "[A-Z]{3}"
              xml:
                attribute: true
            country_name:
              type: string
              description: "The full name of the country that `number` is registered in."
              example: "United Kingdom"
              xml:
                attribute: true
            country_prefix:
              type: string
              description: "The numeric prefix for the country that `number` is registered in."
              example: "44"
              xml:
                attribute: true
            number:
              type: string
              description: "The `number` in your request in the format used by the country the number belongs to."
              example: "07700 900000"
              xml:
                x-text: true # see https://github.com/OAI/OpenAPI-Specification/issues/630
        error:
          type: object
          description: "The error code and status of your request"
          properties:
            code:
              type: string
              description: "The status code"
              example: 0
              xml:
                attribute: true
            status_text:
              type: string
              description: "The status description of your request."
              example: Success
              xml:
                x-text: true # see https://github.com/OAI/OpenAPI-Specification/issues/630

    niResponseXmlStandard:
      type: object
      description: "Standard"
      xml:
        name: lookup
      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
          xml:
            name: request_id
        international_format_number:
          type: string
          description: "The `number` in your request in international format."
          example: "447700900000"
        local_number:
          type: object
          description: "An object containing the `number` in your request in the format used by the country the number belongs to."
          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."
              example: "GB"
              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."
              example: "GBR"
              pattern: "[A-Z]{3}"
              xml:
                attribute: true
            country_name:
              type: string
              description: "The full name of the country that `number` is registered in."
              example: "United Kingdom"
              xml:
                attribute: true
            country_prefix:
              type: string
              description: "The numeric prefix for the country that `number` is registered in."
              example: "44"
              xml:
                attribute: true
            number:
              type: string
              description: "The `number` in your request in the format used by the country the number belongs to."
              example: "07700 900000"
              xml:
                x-text: true # see https://github.com/OAI/OpenAPI-Specification/issues/630
        error:
          type: object
          description: "The error code and status of your request"
          properties:
            code:
              type: string
              description: "The status code"
              example: 0
              xml:
                attribute: true
            status_text:
              type: string
              description: "The status description of your request."
              example: Success
              xml:
                x-text: true # see https://github.com/OAI/OpenAPI-Specification/issues/630
        request_price:
          type: string
          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: string
          description: "Your account balance in EUR after this request."
          example: "1.23456789"
        current_carrier:
          $ref: "#/components/schemas/niCurrentCarrierProperties"
        original_carrier:
          $ref: "#/components/schemas/niInitialCarrierProperties"
        ported:
          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"
          properties:
            ported_message:
              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"
              xml:
                x-text: true
        roaming:
          type: object
          description: "Information about the roaming status for number. This is applicable to mobile numbers only."
          x-nexmo-developer-collection-description-shown: true
          properties:
            status:
              type: string
              description: Roaming status for number 
              enum:
                - unknown
              example: unknown
              xml:
                attribute: true
        caller_identity:
          type: object
          x-nexmo-developer-collection-description-shown: true
          description: "Contains details of the number owner, if `cnam` was set to `true` in the request."
          properties:
            callerType:
              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"
              xml:
                attribute: true
            callerName:
              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"
              xml:
                attribute: true
            firstName:
              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"
              xml:
                attribute: true
            lastName:
              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"
              xml:
                attribute: true
            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:
              # Key is not a typo. Do not change.
              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"

    niResponseXmlAdvanced:
      type: object
      description: "Advanced"
      xml:
        name: lookup
      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
          xml:
            name: request_id
        international_format_number:
          type: string
          description: "The `number` in your request in international format."
          example: "447700900000"
        local_number:
          type: object
          x-nexmo-developer-collection-description-shown: true
          description: "An object containing the `number` in your request in the format used by the country the number belongs to."
          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."
              example: "GB"
              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."
              example: "GBR"
              pattern: "[A-Z]{3}"
              xml:
                attribute: true
            country_name:
              type: string
              description: "The full name of the country that `number` is registered in."
              example: "United Kingdom"
              xml:
                attribute: true
            country_prefix:
              type: string
              description: "The numeric prefix for the country that `number` is registered in."
              example: "44"
              xml:
                attribute: true
            number:
              type: string
              description: "The `number` in your request in the format used by the country the number belongs to."
              example: "07700 900000"
              xml:
                x-text: true # see https://github.com/OAI/OpenAPI-Specification/issues/630
        error:
          type: object
          x-nexmo-developer-collection-description-shown: true
          description: "The error code and status of your request"
          properties:
            code:
              type: string
              description: "The status code"
              example: 0
              xml:
                attribute: true
            status_text:
              type: string
              description: "The status description of your request."
              example: Success
              xml:
                x-text: true # see https://github.com/OAI/OpenAPI-Specification/issues/630
        request_price:
          type: string
          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: string
          description: "Your account balance in EUR after this request."
          example: "1.23456789"
        current_carrier:
          $ref: "#/components/schemas/niCurrentCarrierProperties"
        original_carrier:
          $ref: "#/components/schemas/niInitialCarrierProperties"
        ported:
          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."
          properties:
            ported_message:
              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"
              xml:
                x-text: true
        caller_identity:
          description: "Contains details of the number owner, if `cnam` was set to `true` in the request."
          properties:
            callerType:
              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"
              xml:
                attribute: true
            callerName:
              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"
              xml:
                attribute: true
            firstName:
              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"
              xml:
                attribute: true
            lastName:
              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"
              xml:
                attribute: true
        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"
        firs_name:
          # Key is not a typo. Do not change.
          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: object
          x-nexmo-developer-collection-description-shown: true
          description: "An object indicating whether all information about a phone number has been returned."
          properties:
            code:
              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"
              xml:
                attribute: true
            lookup_outcome_message:
              type: string
              description: "Shows if all information about a phone number has been returned."
              example: "Success"
              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
          example: "reachable"
        roaming:
          $ref: "#/components/schemas/niRoaming"
        valid_number:
          type: string
          description: "Does `number` exist. `unknown` means the number could not be validated. `valid` means the number is valid. `not_valid` means the number is not valid. `inferred_not_valid` means that the number could not be determined as valid or invalid via an external system and the best guess is that the number is invalid. This is applicable to mobile numbers only."
          enum:
            - unknown
            - valid
            - not_valid
            - inferred_not_valid
          example: "valid"
        ip_warnings:
          type: string
          description: "This property is deprecated and can safely be ignored."
          example: "unknown"

    niResponseJsonBasic:
      type: object
      properties:
        status:
          $ref: "#/components/schemas/niBasicStatus"
        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"

    niResponseJsonStandard:
      allOf:
        - $ref: "#/components/schemas/niResponseJsonBasic"
        - type: object
          properties:
            request_price:
              type: string
              description: "The amount in EUR charged to your account."
              example: "0.04000000"
            refund_price:
              type: string
              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: string
              description: "Your account balance in EUR after this request."
              example: "1.23456789"
            current_carrier:
              $ref: "#/components/schemas/niCurrentCarrierProperties"
            original_carrier:
              $ref: "#/components/schemas/niInitialCarrierProperties"
            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:
              oneOf:
              - $ref: "#/components/schemas/niRoaming"
              - type: string
            caller_identity:
              $ref: "#/components/schemas/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"

    niResponseJsonAdvanced:
      type: object
      description: Advanced
      properties:
        status:
          $ref: "#/components/schemas/niStandardAdvancedStatus"
        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: string
          description: "The amount in EUR charged to your account."
          example: "0.04000000"
        refund_price:
          type: string
          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: string
          description: "Your account balance in EUR after this request."
          example: "1.23456789"
        current_carrier:
          $ref: "#/components/schemas/niCurrentCarrierProperties"
        original_carrier:
          $ref: "#/components/schemas/niInitialCarrierProperties"
        ported:
          type: string
          nullable: true
          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:
          oneOf:
            - $ref: "#/components/schemas/niRoaming"
            - type: string
          nullable: true
        caller_identity:
          $ref: "#/components/schemas/niCallerIdentity"
        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. `unknown` means the number could not be validated. `valid` means the number is valid. `not_valid` means the number is not valid. `inferred_not_valid` means that the number could not be determined as valid or invalid via an external system and the best guess is that the number is invalid. This is applicable to mobile numbers only."
          enum:
            - unknown
            - valid
            - not_valid
            - inferred
            - inferred_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"
          nullable: true
      required:
        - status
        - status_message
        - request_id
        - international_format_number
        - national_format_number
        - country_code
        - country_code_iso3
        - country_name
        - country_prefix

    # 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'

    niCurrentCarrierProperties:
      type: object
      x-nexmo-developer-collection-description-shown: true
      description: "Information about the network `number` is currently connected to."
      properties:
        network_code:
          type: string
          nullable: true
          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
          nullable: true
          description: "The full name of the carrier that `number` is associated with."
          xml:
            attribute: true
          example: "Acme Inc"
        country:
          type: string
          nullable: true
          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
          nullable: true
          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"

    niInitialCarrierProperties:
      type: object
      x-nexmo-developer-collection-description-shown: true
      description: "Information about the network `number` was initially connected to."
      properties:
        network_code:
          type: string
          nullable: true
          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
          nullable: true
          description: "The full name of the carrier that `number` is associated with."
          xml:
            attribute: true
          example: "Acme Inc"
        country:
          type: string
          nullable: true
          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
          nullable: true
          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
      description: "Information about the roaming status for `number`. This is applicable to mobile numbers only."
      properties:
        status:
          type: string
          nullable: true
          description: "Is `number` outside its home carrier network."
          enum:
            - unknown
            - roaming
            - not_roaming
          example: roaming
          xml:
            attribute: true
        roaming_country_code:
          type: string
          nullable: true
          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
          xml:
            attribute: true
        roaming_network_code:
          type: string
          nullable: true
          description: "If `number` is `roaming`, this is the id of the carrier network `number` is roaming in."
          example: "12345"
          xml:
            attribute: true
        roaming_network_name:
          type: string
          nullable: true
          description: "If `number` is `roaming`, this is the name of the carrier network `number` is roaming in."
          example: "Acme Inc"
          xml:
            attribute: true

    niCallerIdentity:
      type: object
      description: "Information about the network `number` is currently connected to."
      properties:
        caller_type:
          type: string
          nullable: true
          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
          nullable: true
          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
          nullable: true
          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
          nullable: true
          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"

    niBasicStatus:
      type: integer
      enum:
        - 0
        - 1
        - 3
        - 4
        - 5
        - 9
      example: 0
      description: |
        Code | Text        
        #   -- | --
        #    0 | Success - request accepted for delivery by .
        #    1 | Busy - you have made more requests in the last second than are permitted by your 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 account does not have sufficient credit to process this request.
    niStandardAdvancedStatus:
      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 .
        #          1 | Busy - you have made more requests in the last second than are permitted by your 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 account does not have sufficient credit to process this request.
        #         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.
  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)"