Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
1146 lines (1124 sloc) 47.1 KB
---
openapi: 3.0.0
servers:
- url: 'https://api.nexmo.com/ni'
info:
title: Number Insight API
version: 1.0.0
description: >-
Nexmo's 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](/number-insight/overview#basic-standard-and-advanced-apis). The advanced API is available asynchronously as well as synchronously.
contact:
name: Nexmo DevRel
email: devrel@nexmo.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
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
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/{format}':
parameters:
- $ref: '#/components/parameters/format'
get:
operationId: getNumberInsightAdvanced
summary: Advanced Number Insight (sync)
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'
'/advanced/async/{format}':
parameters:
- $ref: '#/components/parameters/format'
get:
operationId: getNumberInsightAsync
summary: Advanced Number Insight (async)
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
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/niResponseJsonAdvanced'
text/xml:
schema:
$ref: '#/components/schemas/niResponseXmlAdvanced'
responses:
'200':
description: OK
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: "The IP address of the user. If supplied, we will compare this to the country the user's phone is located in and return an error if it does not match."
schema:
type: string
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. Not returned with Number Insight Advanced Async API.'
example: '1.23456789'
xml:
name: remainingBalance
request_price:
type: number
description: 'If there is an internal lookup error, the `refund_price` will reflect the lookup price. If `cnam` is requested for a non-US number the `refund_price` will reflect the `cnam` price. If both of these conditions occur, `refund_price` is the sum of the lookup price and `cnam` price.'
example: '0.01500000'
xml:
name: requestPrice
status:
$ref: '#/components/schemas/niStandardAdvancedStatus'
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: number
description: 'If there is an internal lookup error, the `refund_price` will reflect the lookup price. If `cnam` is requested for a non-US number the `refund_price` will reflect the `cnam` price. If both of these conditions occur, `refund_price` is the sum of the lookup price and `cnam` price.'
example: '0.01500000'
remaining_balance:
type: number
description: 'Your account balance in EUR after this request. Not returned with Number Insight Advanced Async API.'
example: '1.23456789'
current_carrier:
$ref: '#/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
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:
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.'
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'
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: number
description: 'If there is an internal lookup error, the `refund_price` will reflect the lookup price. If `cnam` is requested for a non-US number the `refund_price` will reflect the `cnam` price. If both of these conditions occur, `refund_price` is the sum of the lookup price and `cnam` price.'
example: '0.01500000'
remaining_balance:
type: number
description: 'Your account balance in EUR after this request. Not returned with Number Insight Advanced Async API.'
example: '1.23456789'
current_carrier:
$ref: '#/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:
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.'
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'
ip:
$ref: '#/components/schemas/niIP'
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: 'Warning levels for `ip`'
enum:
- unknown
- no_warning
example: 'no_warning'
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: number
description: 'The amount in EUR charged to your account.'
example: "0.04000000"
refund_price:
type: number
description: 'If there is an internal lookup error, the `refund_price` will reflect the lookup price. If `cnam` is requested for a non-US number the `refund_price` will reflect the `cnam` price. If both of these conditions occur, `refund_price` is the sum of the lookup price and `cnam` price.'
example: '0.01500000'
remaining_balance:
type: number
description: 'Your account balance in EUR after this request. Not returned with Number Insight Advanced Async API.'
example: '1.23456789'
current_carrier:
$ref: '#/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:
$ref: '#/components/schemas/niRoaming'
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: number
description: 'The amount in EUR charged to your account.'
example: "0.04000000"
refund_price:
type: number
description: 'If there is an internal lookup error, the `refund_price` will reflect the lookup price. If `cnam` is requested for a non-US number the `refund_price` will reflect the `cnam` price. If both of these conditions occur, `refund_price` is the sum of the lookup price and `cnam` price.'
example: '0.01500000'
remaining_balance:
type: number
description: 'Your account balance in EUR after this request. Not returned with Number Insight Advanced Async API.'
example: '1.23456789'
current_carrier:
$ref: '#/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:
$ref: '#/components/schemas/niRoaming'
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'
ip:
$ref: '#/components/schemas/niIP'
ip_warnings:
type: string
description: 'Warning levels for `ip`'
enum:
- unknown
- no_warning
example: 'no_warning'
required:
- status
- status_message
- request_id
- international_format_number
- national_format_number
- country_code
- country_code_iso3
- country_name
- country_prefix
# niCarrier:
# type: object
# 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
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'
niInitialCarrierProperties:
type: object
x-nexmo-developer-collection-description-shown: true
description: 'Information about the network `number` is currently connected to.'
properties:
network_code:
type: string
description: 'The [https://en.wikipedia.org/wiki/Mobile_country_code](https://en.wikipedia.org/wiki/Mobile_country_code) for the carrier`number` is associated with. Unreal numbers are marked as`unknown` and the request is rejected altogether if the number is impossible according to the [E.164](https://en.wikipedia.org/wiki/E.164) guidelines.'
xml:
attribute: true
example: '12345'
name:
type: string
description: 'The full name of the carrier that `number` is associated with.'
xml:
attribute: true
example: 'Acme Inc'
country:
type: string
description: 'The country that `number` is associated with. This is in ISO 3166-1 alpha-2 format.'
xml:
attribute: true
example: 'GB'
network_type:
type: string
description: 'The type of network that `number` is associated with.'
enum:
- mobile
- landline
- landline_premium
- landline_tollfree
- virtual
- unknown
- pager
xml:
attribute: true
example: 'mobile'
niRoaming:
type: object
description: 'Information about the roaming status for `number`. This is applicable to mobile numbers only.'
properties:
status:
type: string
description: 'Is `number` outside its home carrier network.'
enum:
- unknown
- roaming
- not_roaming
example: roaming
xml:
attribute: true
roaming_country_code:
type: string
description: 'If `number` is `roaming`, this is the [code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the country `number` is roaming in.'
example: US
xml:
attribute: true
roaming_network_code:
type: string
description: 'If `number` is `roaming`, this is the id of the carrier network `number` is roaming in.'
example: 12345
xml:
attribute: true
roaming_network_name:
type: string
description: 'If `number` is `roaming`, this is the name of the carrier network `number` is roaming in.'
example: 'Acme Inc'
xml:
attribute: true
niIP:
type: object
description: 'Information about the provided IP address'
properties:
address:
type: string
description: 'The ip address you specified in the request.'
example: '123.0.0.255'
xml:
attribute: true
ip_match_level:
type: string
description: 'The match status between ip and number parameters.'
enum:
- 'country'
- 'mismatch'
example: 'country'
xml:
attribute: true
ip_country:
type: string
description: 'The country that `ip` is allocated to.'
example: 'GB'
xml:
attribute: true
ip_city:
type: string
description: 'The city that `ip` is allocated to.'
example: 'London'
xml:
attribute: true
niCallerIdentity:
type: object
description: 'Information about the network `number` is currently connected to.'
properties:
caller_type:
type: string
description: 'The value will be `business` if the owner of a phone number is a business. If the owner is an individual the value will be `consumer`. The value will be `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.'
enum:
- business
- consumer
- unknown
example: 'consumer'
caller_name:
type: string
description: 'Full name of the person or business who owns the phone number. `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.'
example: 'John Smith'
first_name:
type: string
description: 'First name of the person who owns the phone number if the owner is an individual. This parameter is only present if `cnam` had a value of `true` within the request.'
example: 'John'
last_name:
type: string
description: 'Last name of the person who owns the phone number if the owner is an individual. This parameter is only present if `cnam` had a value of `true` within the request.'
example: 'Smith'
niBasicStatus:
type: integer
enum:
- 0
- 1
- 3
- 4
- 5
- 9
example: 0
description: |
Code | Text
-- | --
0 | Success - request accepted for delivery by Nexmo.
1 | Busy - you have made more requests in the last second than are permitted by your Nexmo account. Please retry.
3 | Invalid - your request is incomplete and missing some mandatory parameters.
4 | Invalid credentials - the _api_key_ or _api_secret_ you supplied is either not valid or has been disabled.
5 | Internal Error - the format of the recipient address is not valid.
9 | Partner quota exceeded - your Nexmo account does not have sufficient credit to process this request.
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 Nexmo.
1 | Busy - you have made more requests in the last second than are permitted by your Nexmo account. Please retry.
3 | Invalid - your request is incomplete and missing some mandatory parameters.
4 | Invalid credentials - the _api_key_ or _api_secret_ you supplied is either not valid or has been disabled.
5 | Internal Error - the format of the recipient address is not valid.
9 | Partner quota exceeded - your Nexmo account does not have sufficient credit to process this request.
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)'