Vonage Standard API

openapi: 3.2.0
info:
  title: Vonage Standard API
  version: 1.2.1
  contact:
    name: Vonage DevRel
    email: devrel@vonage.com
    url: https://developer.nexmo.com/
  license:
    name: The MIT License (MIT)
    url: https://opensource.org/licenses/MIT
  termsOfService: https://www.nexmo.com/terms-of-use
  x-metaDescription: Find quick answers to questions about the Vonage Number Insight API in this reference guide. Learn more in Vonage's API documentation.
  x-metaTitle: Vonage Number Insight API Reference | Vonage API Documentation
  description: 'Operations tagged Standard across 2 of this provider''s published API definitions: vonage-number-insight-openapi.json, vonage-number-insight-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.nexmo.com/ni
security:
- basicAuth: []
tags:
- name: Standard
paths:
  /standard/{format}:
    parameters:
    - $ref: '#/components/parameters/format'
    get:
      operationId: getNumberInsightStandard
      summary: Standard Number Insight
      description: 'Provides standard number insight 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:
                oneOf:
                - $ref: '#/components/schemas/niResponseJsonStandard'
            text/xml:
              schema:
                $ref: '#/components/schemas/niResponseXmlStandard'
      tags:
      - Standard
    servers:
    - url: https://api.nexmo.com/ni
components:
  parameters:
    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 feature is available only for US numbers but not all US numbers are supported. It incurs an additional charge for US numbers regardless of whether any information is returned. For non-US numbers and for non-approved users, the CNAM response attributes are omitted and no additional charges are incurred.
      schema:
        type: boolean
        default: false
    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}'
  schemas:
    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.

        '
    niInitialCarrierProperties:
      type:
      - object
      - 'null'
      x-nexmo-developer-collection-description-shown: true
      description: Information about the network `number` was initially connected to.
      properties:
        network_code:
          type:
          - string
          - 'null'
          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.
          xml:
            attribute: true
          example: '12345'
        name:
          type:
          - string
          - 'null'
          description: The full name of the carrier that `number` is associated with.
          xml:
            attribute: true
          example: Acme Inc
        country:
          type:
          - string
          - 'null'
          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
          - 'null'
          description: The type of network that `number` is associated with.
          enum:
          - mobile
          - landline
          - landline_premium
          - landline_tollfree
          - virtual
          - unknown
          - pager
          - 'null'
          xml:
            attribute: true
          example: mobile
    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
        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
        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:
          allOf:
          - $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:
          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:
            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
              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
              xml:
                attribute: true
            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
              xml:
                attribute: true
            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
              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. `unknown` if this information is not available.
              example: Smith
            firs_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. `unknown` if this information is not available.
              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
    niCallerIdentity:
      type: object
      description: Information about the network `number` is currently connected to.
      properties:
        caller_type:
          type: string
          description: The value will be `business` if the owner of a phone number is a business. If the owner is an individual the value will be `consumer`. The value will be `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.
          enum:
          - business
          - consumer
          - unknown
          example: consumer
        caller_name:
          type: string
          description: Full name of the person or business who owns the phone number. `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.
          example: John Smith
        first_name:
          type: string
          description: First name of the person who owns the phone number if the owner is an individual. This parameter is only present if `cnam` had a value of `true` within the request. `unknown` if this information is not available.
          example: John
        last_name:
          type: string
          description: Last name of the person who owns the phone number if the owner is an individual. This parameter is only present if `cnam` had a value of `true` within the request. `unknown` if this information is not available.
          example: Smith
    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'
    niCurrentCarrierProperties:
      type:
      - object
      - 'null'
      x-nexmo-developer-collection-description-shown: true
      description: Information about the network `number` is currently connected to. While in some cases and regions it may return information for non-mobile numbers, this field is supported only for mobile numbers.
      properties:
        network_code:
          type:
          - string
          - 'null'
          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.
          xml:
            attribute: true
          example: '12345'
        name:
          type:
          - string
          - 'null'
          description: The full name of the carrier that `number` is associated with.
          xml:
            attribute: true
          example: Acme Inc
        country:
          type:
          - string
          - 'null'
          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
          - 'null'
          description: The type of network that `number` is associated with.
          enum:
          - mobile
          - landline
          - landline_premium
          - landline_tollfree
          - virtual
          - unknown
          - pager
          - 'null'
          xml:
            attribute: true
          example: mobile
    niResponseJsonStandard:
      description: Standard Response
      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:
            allOf:
            - $ref: '#/components/schemas/niCurrentCarrierProperties'
          original_carrier:
            $ref: '#/components/schemas/niInitialCarrierProperties'
          ported:
            type:
            - string
            - 'null'
            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
          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. `unknown` if this information is not available.
            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. `unknown` if this information is not available.
            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
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
externalDocs:
  url: https://developer.nexmo.com/api/number-insight
  x-sha1: 081f6d985e2e4a75586da1654fde880a96885405
x-refined-from:
- vonage-number-insight-openapi.json
- vonage-number-insight-openapi.yml
x-errors:
  validation:
    description: The provided payload is invalid
    resolution: 'Modify your request to provide a valid payload.

      * Minimum 8 characters

      * Maximum 25 characters

      * Minimum 1 lower case character

      * Minimum 1 upper case character

      * Minimum 1 digit

      '
    link:
      text: View API reference
      url: /api/account#createAPISecret
  delete-last-secret:
    description: You can not delete your only API secret
    resolution: Add another API secret before deleting this one