openapi: 3.0.0
servers:
  - url: https://api.nexmo.com/ni
info:
  contact:
    email: devrel@vonage.com
    name: Vonage DevRel
    url: https://developer.nexmo.com/
  description: "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."
  license:
    name: The MIT License (MIT)
    url: https://opensource.org/licenses/MIT
  termsOfService: https://www.nexmo.com/terms-of-use
  title: Number Insight API
  version: 1.2.1
  x-logo:
    url: https://www.vonage.com/content/dam/vonage/us-en/api/illustrations/Mobile_APIs_Services.svg
  x-origin:
    - format: openapi
      url: https://raw.githubusercontent.com/nexmo/api-specification/master/definitions/number-insight.yml
      version: "3.0"
  x-providerName: nexmo.com
  x-serviceName: number-insight
externalDocs:
  url: https://developer.nexmo.com/api/number-insight
  x-sha1: 081f6d985e2e4a75586da1654fde880a96885405
security:
  - apiKey: []
    apiSecret: []
paths:
  /advanced/async/{format}:
    get:
      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.
      operationId: getNumberInsightAsync
      parameters:
        - $ref: "#/components/parameters/callback"
        - $ref: "#/components/parameters/number"
        - $ref: "#/components/parameters/country"
        - $ref: "#/components/parameters/cnam"
        - $ref: "#/components/parameters/ip"
      responses:
        "200":
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/niResponseAsync"
            text/xml:
              schema:
                $ref: "#/components/schemas/niResponseAsync"
          description: OK
      summary: Advanced Number Insight (async)
    parameters:
      - $ref: "#/components/parameters/format"
  /advanced/{format}:
    get:
      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.
      operationId: getNumberInsightAdvanced
      parameters:
        - $ref: "#/components/parameters/real_time_data"
        - $ref: "#/components/parameters/number"
        - $ref: "#/components/parameters/country"
        - $ref: "#/components/parameters/cnam"
        - $ref: "#/components/parameters/ip"
      responses:
        "200":
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/niResponseJsonAdvancedSync"
                  - $ref: "#/components/schemas/niResponseJsonAdvancedRoamingUnknown"
            text/xml:
              schema:
                $ref: "#/components/schemas/niResponseXmlAdvanced"
          description: OK
      summary: Advanced Number Insight (sync)
    parameters:
      - $ref: "#/components/parameters/format"
  /basic/{format}:
    get:
      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.
      operationId: getNumberInsightBasic
      parameters:
        - $ref: "#/components/parameters/number"
        - $ref: "#/components/parameters/country"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/niResponseJsonBasic"
            text/xml:
              schema:
                $ref: "#/components/schemas/niResponseXmlBasic"
          description: OK
      summary: Basic Number Insight
    parameters:
      - $ref: "#/components/parameters/format"
  /standard/{format}:
    get:
      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.
      operationId: getNumberInsightStandard
      parameters:
        - $ref: "#/components/parameters/number"
        - $ref: "#/components/parameters/country"
        - $ref: "#/components/parameters/cnam"
      responses:
        "200":
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/niResponseJsonStandard"
            text/xml:
              schema:
                $ref: "#/components/schemas/niResponseXmlStandard"
          description: OK
      summary: Standard Number Insight
    parameters:
      - $ref: "#/components/parameters/format"
components:
  parameters:
    callback:
      description: The callback URL
      example: https://example.com/callback
      in: query
      name: callback
      required: true
      schema:
        format: uriref
        type: string
    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
      in: query
      name: cnam
      schema:
        default: false
        type: boolean
    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
      in: query
      name: country
      schema:
        pattern: "[A-Z]{2}"
        type: string
    format:
      description: The format of the response
      example: json
      in: path
      name: format
      required: true
      schema:
        enum:
          - json
          - xml
        type: string
    ip:
      deprecated: true
      description: "This parameter is deprecated as we are no longer able to retrieve reliable IP data globally from carriers. "
      example: 123.0.0.255
      in: query
      name: ip
      schema:
        type: string
    number:
      description: A single phone number that you need insight about in national or international format.
      example: "447700900000"
      in: query
      name: number
      required: true
      schema:
        pattern: ^[0-9-+\(\)\s]*$
        type: string
    real_time_data:
      description: A boolean to choose whether to get real time data back in the response.
      example: "true"
      in: query
      name: real_time_data
      required: false
      schema:
        type: boolean
  schemas:
    niAsyncResponse:
      properties:
        id:
          format: int64
          type: integer
        name:
          type: string
        tag:
          type: string
      required:
        - id
        - name
    niBasicStatus:
      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.
      enum:
        - 0
        - 1
        - 3
        - 4
        - 5
        - 9
      example: 0
      type: integer
    niCallerIdentity:
      description: Information about the network `number` is currently connected to.
      properties:
        caller_name:
          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
          type: string
        caller_type:
          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
          type: string
        first_name:
          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
          type: string
        last_name:
          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
          type: string
      type: object
    niCurrentCarrierProperties:
      description: Information about the network `number` is currently connected to.
      nullable: true
      properties:
        country:
          description: The country that `number` is associated with. This is in ISO 3166-1 alpha-2   format.
          example: GB
          nullable: true
          type: string
          xml:
            attribute: true
        name:
          description: The full name of the carrier that `number` is associated with.
          example: Acme Inc
          nullable: true
          type: string
          xml:
            attribute: true
        network_code:
          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`null` 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"
          nullable: true
          type: string
          xml:
            attribute: true
        network_type:
          description: The type of network that `number` is associated with.
          enum:
            - mobile
            - landline
            - landline_premium
            - landline_tollfree
            - virtual
            - unknown
            - pager
            - "null"
          example: mobile
          nullable: true
          type: string
          xml:
            attribute: true
      type: object
      x-nexmo-developer-collection-description-shown: true
    niInitialCarrierProperties:
      description: Information about the network `number` was initially connected to.
      nullable: true
      properties:
        country:
          description: The country that `number` is associated with. This is in ISO 3166-1 alpha-2   format.
          example: GB
          nullable: true
          type: string
          xml:
            attribute: true
        name:
          description: The full name of the carrier that `number` is associated with.
          example: Acme Inc
          nullable: true
          type: string
          xml:
            attribute: true
        network_code:
          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`null` 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"
          nullable: true
          type: string
          xml:
            attribute: true
        network_type:
          description: The type of network that `number` is associated with.
          enum:
            - mobile
            - landline
            - landline_premium
            - landline_tollfree
            - virtual
            - unknown
            - pager
            - "null"
          example: mobile
          nullable: true
          type: string
          xml:
            attribute: true
      type: object
      x-nexmo-developer-collection-description-shown: true
    niRealtimeData:
      description: Real time data about the `number`
      nullable: true
      properties:
        active_status:
          description: Whether the end-user's phone number is active within an operator's `network`. Can be `active`, `inactive` or null.
          example: "true"
          type: string
        handset_status:
          description: Whether the end-user's handset is turned on or off.
          example: On
          type: string
      type: object
    niResponseAsync:
      properties:
        error_text:
          description: "The status description of your request. Note: This field is equivalent to `status_message` field in the other endpoints"
          example: Success
          type: string
        number:
          description: The `number` in your request
          example: "447700900000"
          type: string
        remaining_balance:
          description: Your account balance in EUR after this request.
          example: "1.23456789"
          type: string
          xml:
            name: remainingBalance
        request_id:
          description: The unique identifier for your request. This is a alphanumeric string up to 40 characters.
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
          maxLength: 40
          type: string
          xml:
            name: requestId
        request_price:
          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"
          type: string
          xml:
            name: requestPrice
        status:
          $ref: "#/components/schemas/niStandardAdvancedStatus"
      type: object
      xml:
        name: lookup
    niResponseJsonAdvancedAsync:
      description: Advanced Response (Async)
      properties:
        caller_identity:
          $ref: "#/components/schemas/niCallerIdentity"
        country_code:
          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}"
          type: string
        country_code_iso3:
          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}"
          type: string
        country_name:
          description: The full name of the country that `number` is registered in.
          example: United Kingdom
          type: string
        country_prefix:
          description: The numeric prefix for the country that `number` is registered in.
          example: "44"
          type: string
        current_carrier:
          $ref: "#/components/schemas/niCurrentCarrierProperties"
        international_format_number:
          description: The `number` in your request in international format.
          example: "447700900000"
          type: string
        lookup_outcome:
          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
          type: integer
        lookup_outcome_message:
          description: Shows if all information about a phone number has been returned.
          example: Success
          type: string
        national_format_number:
          description: The `number` in your request in the format used by the country the number belongs to.
          example: 07700 900000
          type: string
        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.
          enum:
            - unknown
            - ported
            - not_ported
            - assumed_not_ported
            - assumed_ported
            - "null"
          example: not_ported
          nullable: true
          type: string
        reachable:
          description: Can you call `number` now. This is applicable to mobile numbers only.
          enum:
            - unknown
            - reachable
            - undeliverable
            - absent
            - bad_number
            - blacklisted
            - "null"
          example: reachable
          nullable: true
          type: string
        refund_price:
          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"
          type: string
        remaining_balance:
          description: Your account balance in EUR after this request.
          example: "1.23456789"
          type: string
        request_id:
          description: The unique identifier for your request. This is a alphanumeric string up to 40 characters.
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
          maxLength: 40
          type: string
        request_price:
          description: The amount in EUR charged to your account.
          example: "0.04000000"
          type: string
        roaming:
          $ref: "#/components/schemas/niRoaming"
        status:
          $ref: "#/components/schemas/niStandardAdvancedStatus"
        status_message:
          description: The status description of your request.
          example: Success
          type: string
        valid_number:
          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
          type: string
      required:
        - status
        - status_message
        - request_id
        - international_format_number
        - national_format_number
        - country_code
        - country_code_iso3
        - country_name
        - country_prefix
      type: object
    niResponseJsonAdvancedRoamingUnknown:
      description: Unknown Roaming
      properties:
        caller_identity:
          $ref: "#/components/schemas/niCallerIdentity"
        country_code:
          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}"
          type: string
        country_code_iso3:
          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}"
          type: string
        country_name:
          description: The full name of the country that `number` is registered in.
          example: United Kingdom
          type: string
        country_prefix:
          description: The numeric prefix for the country that `number` is registered in.
          example: "44"
          type: string
        current_carrier:
          $ref: "#/components/schemas/niCurrentCarrierProperties"
        international_format_number:
          description: The `number` in your request in international format.
          example: "447700900000"
          type: string
        lookup_outcome:
          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
          type: integer
        lookup_outcome_message:
          description: Shows if all information about a phone number has been returned.
          example: Success
          type: string
        national_format_number:
          description: The `number` in your request in the format used by the country the number belongs to.
          example: 07700 900000
          type: string
        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.
          enum:
            - unknown
            - ported
            - not_ported
            - assumed_not_ported
            - assumed_ported
            - "null"
          example: not_ported
          nullable: true
          type: string
        reachable:
          description: Can you call `number` now. This is applicable to mobile numbers only.
          enum:
            - unknown
            - reachable
            - undeliverable
            - absent
            - bad_number
            - blacklisted
            - "null"
          example: reachable
          nullable: true
          type: string
        refund_price:
          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"
          type: string
        remaining_balance:
          description: Your account balance in EUR after this request.
          example: "1.23456789"
          type: string
        request_id:
          description: The unique identifier for your request. This is a alphanumeric string up to 40 characters.
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
          maxLength: 40
          type: string
        request_price:
          description: The amount in EUR charged to your account.
          example: "0.04000000"
          type: string
        roaming:
          enum:
            - unknown
          example: unknown
          type: string
        status:
          $ref: "#/components/schemas/niStandardAdvancedStatus"
        status_message:
          description: The status description of your request.
          example: Success
          type: string
        valid_number:
          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
          type: string
      required:
        - status
        - status_message
        - request_id
        - international_format_number
        - national_format_number
        - country_code
        - country_code_iso3
        - country_name
        - country_prefix
      type: object
    niResponseJsonAdvancedSync:
      description: Advanced Response (sync)
      properties:
        caller_identity:
          $ref: "#/components/schemas/niCallerIdentity"
        country_code:
          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}"
          type: string
        country_code_iso3:
          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}"
          type: string
        country_name:
          description: The full name of the country that `number` is registered in.
          example: United Kingdom
          type: string
        country_prefix:
          description: The numeric prefix for the country that `number` is registered in.
          example: "44"
          type: string
        current_carrier:
          $ref: "#/components/schemas/niCurrentCarrierProperties"
        international_format_number:
          description: The `number` in your request in international format.
          example: "447700900000"
          type: string
        lookup_outcome:
          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
          type: integer
        lookup_outcome_message:
          description: Shows if all information about a phone number has been returned.
          example: Success
          type: string
        national_format_number:
          description: The `number` in your request in the format used by the country the number belongs to.
          example: 07700 900000
          type: string
        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.
          enum:
            - unknown
            - ported
            - not_ported
            - assumed_not_ported
            - assumed_ported
            - "null"
          example: not_ported
          nullable: true
          type: string
        reachable:
          description: Can you call `number` now. This is applicable to mobile numbers only.
          enum:
            - unknown
            - reachable
            - undeliverable
            - absent
            - bad_number
            - blacklisted
            - "null"
          example: reachable
          nullable: true
          type: string
        real_time_data:
          $ref: "#/components/schemas/niRealtimeData"
        refund_price:
          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"
          type: string
        remaining_balance:
          description: Your account balance in EUR after this request.
          example: "1.23456789"
          type: string
        request_id:
          description: The unique identifier for your request. This is a alphanumeric string up to 40 characters.
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
          maxLength: 40
          type: string
        request_price:
          description: The amount in EUR charged to your account.
          example: "0.04000000"
          type: string
        roaming:
          $ref: "#/components/schemas/niRoaming"
        status:
          $ref: "#/components/schemas/niStandardAdvancedStatus"
        status_message:
          description: The status description of your request.
          example: Success
          type: string
        valid_number:
          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
          type: string
      required:
        - status
        - status_message
        - request_id
        - international_format_number
        - national_format_number
        - country_code
        - country_code_iso3
        - country_name
        - country_prefix
      type: object
    niResponseJsonBasic:
      properties:
        country_code:
          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}"
          type: string
        country_code_iso3:
          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}"
          type: string
        country_name:
          description: The full name of the country that `number` is registered in.
          example: United Kingdom
          type: string
        country_prefix:
          description: The numeric prefix for the country that `number` is registered in.
          example: "44"
          type: string
        international_format_number:
          description: The `number` in your request in international format.
          example: "447700900000"
          type: string
        national_format_number:
          description: The `number` in your request in the format used by the country the number belongs to.
          example: 07700 900000
          type: string
        request_id:
          description: The unique identifier for your request. This is a alphanumeric string up to 40 characters.
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
          maxLength: 40
          type: string
        status:
          $ref: "#/components/schemas/niBasicStatus"
        status_message:
          description: The status description of your request.
          example: Success
          type: string
      type: object
    niResponseJsonStandard:
      allOf:
        - $ref: "#/components/schemas/niResponseJsonBasic"
        - properties:
            caller_identity:
              $ref: "#/components/schemas/niCallerIdentity"
            caller_name:
              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
              type: string
            caller_type:
              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
              type: string
            current_carrier:
              allOf:
                - $ref: "#/components/schemas/niCurrentCarrierProperties"
              nullable: true
            first_name:
              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
              type: string
            last_name:
              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
              type: string
            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.
              enum:
                - unknown
                - ported
                - not_ported
                - assumed_not_ported
                - assumed_ported
                - "null"
              example: not_ported
              nullable: true
              type: string
            refund_price:
              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"
              type: string
            remaining_balance:
              description: Your account balance in EUR after this request.
              example: "1.23456789"
              type: string
            request_price:
              description: The amount in EUR charged to your account.
              example: "0.04000000"
              type: string
          type: object
      description: Standard Response
    niResponseJsonStandardRoamingUnknown:
      allOf:
        - $ref: "#/components/schemas/niResponseJsonBasic"
        - properties:
            caller_identity:
              $ref: "#/components/schemas/niCallerIdentity"
            caller_name:
              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
              type: string
            caller_type:
              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
              type: string
            current_carrier:
              allOf:
                - $ref: "#/components/schemas/niCurrentCarrierProperties"
              nullable: true
            first_name:
              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
              type: string
            last_name:
              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
              type: string
            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.
              enum:
                - unknown
                - ported
                - not_ported
                - assumed_not_ported
                - assumed_ported
                - "null"
              example: not_ported
              nullable: true
              type: string
            refund_price:
              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"
              type: string
            remaining_balance:
              description: Your account balance in EUR after this request.
              example: "1.23456789"
              type: string
            request_price:
              description: The amount in EUR charged to your account.
              example: "0.04000000"
              type: string
          type: object
      description: Unknown Roaming
    niResponseXmlAdvanced:
      description: Advanced
      properties:
        caller_identity:
          description: Contains details of the number owner, if `cnam` was set to `true` in the request.
          properties:
            caller-name:
              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
              type: string
              xml:
                attribute: true
            caller-type:
              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
              type: string
              xml:
                attribute: true
            first-name:
              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
              type: string
              xml:
                attribute: true
            last-name:
              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
              type: string
              xml:
                attribute: true
        caller_name:
          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
          type: string
        caller_type:
          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
          type: string
        current_carrier:
          $ref: "#/components/schemas/niCurrentCarrierProperties"
        error:
          description: The error code and status of your request
          properties:
            code:
              description: The status code
              example: 0
              type: string
              xml:
                attribute: true
            status_text:
              description: The status description of your request.
              example: Success
              type: string
              xml:
                x-text: true
          type: object
          x-nexmo-developer-collection-description-shown: true
        firs_name:
          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
          type: string
        international_format_number:
          description: The `number` in your request in international format.
          example: "447700900000"
          type: string
        ip_warnings:
          description: This property is deprecated and can safely be ignored.
          example: unknown
          nullable: true
          type: string
        last_name:
          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
          type: string
        local_number:
          description: An object containing the `number` in your request in the format used by the country the number belongs to.
          properties:
            country_code:
              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}"
              type: string
              xml:
                attribute: true
            country_code_iso3:
              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}"
              type: string
              xml:
                attribute: true
            country_name:
              description: The full name of the country that `number` is registered in.
              example: United Kingdom
              type: string
              xml:
                attribute: true
            country_prefix:
              description: The numeric prefix for the country that `number` is registered in.
              example: "44"
              type: string
              xml:
                attribute: true
            number:
              description: The `number` in your request in the format used by the country the number belongs to.
              example: 07700 900000
              type: string
              xml:
                x-text: true
          type: object
          x-nexmo-developer-collection-description-shown: true
        lookup_outcome:
          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:
              description: Shows if all information about a phone number has been returned.
              example: Success
              type: string
              xml:
                x-text: true
          type: object
          x-nexmo-developer-collection-description-shown: true
        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.
          nullable: true
          properties:
            ported_message:
              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
              type: string
              xml:
                x-text: true
        reachable:
          description: Can you call `number` now. This is applicable to mobile numbers only.
          enum:
            - unknown
            - reachable
            - undeliverable
            - absent
            - bad_number
            - blacklisted
            - "null"
          example: reachable
          nullable: true
          type: string
        remaining_balance:
          description: Your account balance in EUR after this request.
          example: "1.23456789"
          type: string
        request_id:
          description: The unique identifier for your request. This is a alphanumeric string up to 40 characters.
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
          maxLength: 40
          type: string
          xml:
            name: request_id
        request_price:
          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"
          type: string
        roaming:
          $ref: "#/components/schemas/niRoaming"
        valid_number:
          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
          type: string
      type: object
      xml:
        name: lookup
    niResponseXmlBasic:
      description: Basic
      properties:
        error:
          description: The error code and status of your request
          properties:
            code:
              description: The status code
              example: 0
              type: string
              xml:
                attribute: true
            status_text:
              description: The status description of your request.
              example: Success
              type: string
              xml:
                x-text: true
          type: object
        international_format_number:
          description: The `number` in your request in international format.
          example: "447700900000"
          type: string
        local_number:
          description: An object containing the `number` in your request in the format used by the country the number belongs to.
          properties:
            country_code:
              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}"
              type: string
              xml:
                attribute: true
            country_code_iso3:
              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}"
              type: string
              xml:
                attribute: true
            country_name:
              description: The full name of the country that `number` is registered in.
              example: United Kingdom
              type: string
              xml:
                attribute: true
            country_prefix:
              description: The numeric prefix for the country that `number` is registered in.
              example: "44"
              type: string
              xml:
                attribute: true
            number:
              description: The `number` in your request in the format used by the country the number belongs to.
              example: 07700 900000
              type: string
              xml:
                x-text: true
          type: object
        request_id:
          description: The unique identifier for your request. This is a alphanumeric string up to 40 characters.
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
          maxLength: 40
          type: string
          xml:
            name: request_id
      type: object
      xml:
        name: format
    niResponseXmlStandard:
      description: Standard
      properties:
        caller_identity:
          description: Contains details of the number owner, if `cnam` was set to `true` in the request.
          properties:
            caller-name:
              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
              type: string
              xml:
                attribute: true
            caller-type:
              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
              type: string
              xml:
                attribute: true
            caller_name:
              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
              type: string
            caller_type:
              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
              type: string
            firs_name:
              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
              type: string
            first-name:
              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
              type: string
              xml:
                attribute: true
            last-name:
              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
              type: string
              xml:
                attribute: true
            last_name:
              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
              type: string
          type: object
          x-nexmo-developer-collection-description-shown: true
        current_carrier:
          allOf:
            - $ref: "#/components/schemas/niCurrentCarrierProperties"
          nullable: true
        error:
          description: The error code and status of your request
          properties:
            code:
              description: The status code
              example: 0
              type: string
              xml:
                attribute: true
            status_text:
              description: The status description of your request.
              example: Success
              type: string
              xml:
                x-text: true
          type: object
        international_format_number:
          description: The `number` in your request in international format.
          example: "447700900000"
          type: string
        local_number:
          description: An object containing the `number` in your request in the format used by the country the number belongs to.
          properties:
            country_code:
              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}"
              type: string
              xml:
                attribute: true
            country_code_iso3:
              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}"
              type: string
              xml:
                attribute: true
            country_name:
              description: The full name of the country that `number` is registered in.
              example: United Kingdom
              type: string
              xml:
                attribute: true
            country_prefix:
              description: The numeric prefix for the country that `number` is registered in.
              example: "44"
              type: string
              xml:
                attribute: true
            number:
              description: The `number` in your request in the format used by the country the number belongs to.
              example: 07700 900000
              type: string
              xml:
                x-text: true
          type: object
        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
          nullable: true
          properties:
            ported_message:
              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
              type: string
              xml:
                x-text: true
        remaining_balance:
          description: Your account balance in EUR after this request.
          example: "1.23456789"
          type: string
        request_id:
          description: The unique identifier for your request. This is a alphanumeric string up to 40 characters.
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
          maxLength: 40
          type: string
          xml:
            name: request_id
        request_price:
          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"
          type: string
      type: object
      xml:
        name: lookup
    niRoaming:
      description: Information about the roaming status for `number`. This is applicable to mobile numbers only. If unknown, this may return a string of `unknown` instead of an object.
      nullable: true
      properties:
        roaming_country_code:
          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
          type: string
          xml:
            attribute: true
        roaming_network_code:
          description: If `number` is `roaming`, this is the id of the carrier network `number` is roaming in.
          example: "12345"
          type: string
          xml:
            attribute: true
        roaming_network_name:
          description: If `number` is `roaming`, this is the name of the carrier network `number` is roaming in.
          example: Acme Inc
          type: string
          xml:
            attribute: true
        status:
          description: Is `number` outside its home carrier network.
          enum:
            - roaming
            - not_roaming
          example: roaming
          type: string
          xml:
            attribute: true
      type: object
    niStandardAdvancedStatus:
      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.
      enum:
        - 0
        - 1
        - 3
        - 4
        - 5
        - 9
        - 19
        - 43
        - 44
        - 45
        - 999
      example: 0
      type: integer
  securitySchemes:
    apiKey:
      description: You can find your API key in your [account overview](https://dashboard.nexmo.com/account-overview)
      in: query
      name: api_key
      type: apiKey
    apiSecret:
      description: You can find your API secret in your [account overview](https://dashboard.nexmo.com/account-overview)
      in: query
      name: api_secret
      type: apiKey
x-webhooks:
  asyncResponse:
    "{$request.query.callback}":
      post:
        requestBody:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/niResponseJsonAdvancedAsync"
            text/xml:
              schema:
                $ref: "#/components/schemas/niResponseXmlAdvanced"
        responses:
          "200":
            description: OK
        summary: Asynchronous response
  asyncResponseUnknownRoaming:
    "{$request.query.callback}":
      post:
        description: Contains the response to your Number Insight Advanced API request.
        operationId: asyncCallbackRoamingUnknown
        requestBody:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/niResponseJsonAdvancedRoamingUnknown"
            text/xml:
              schema:
                $ref: "#/components/schemas/niResponseXmlAdvanced"
        responses:
          "200":
            description: OK
        summary: Asynchronous response with Unknown Roaming
