Vonage's Number Insight API provides details about the validity, reachability and roaming status of a phone number, as well as giving you details on how to format the number properly in your application. There are three levels of the Number Insight API available: - Basic - Standard - Advanced The advanced API is available asynchronously as well as synchronously.
swagger: '2.0'
info:
title: Number Insight - Vonage
version: "v1.1.1"
termsOfService: 'https://developer.kpn.com/legal'
contact:
name: API Support
email: api_developer@kpn.com
url: 'https://developer.kpn.com/support'
description: >-
Vonage's Number Insight API provides details about the validity, reachability
and roaming status of a phone number, as well as giving you details on how
to format the number properly in your application. There are three levels of the
Number Insight API available:
- Basic
- Standard
- Advanced
The advanced API is available asynchronously as well as synchronously.
## [Source view](https://app.swaggerhub.com/apis/kpn/number-insight-nexmo/)<br/>
[Documentation view](https://app.swaggerhub.com/apis-docs/kpn/number-insight-nexmo/)
---
## [KPN Developer](https://developer.kpn.com/)<br/>
[Getting Started](https://developer.kpn.com/getting-started)
---
host: api-prd.kpn.com
basePath: /communication/nexmo/number-insight
externalDocs:
description: HTTP response headers
url: https://developer.kpn.com/documentation-response-headers
schemes:
- https
paths:
'/{level}':
post:
summary: Synchronously get information about a phone number
operationId: NumberInsight
tags:
- Request
description: >-
**Number Insight Basic**
You can use Vonage's Number Insight Basic API to retrieve local and
international representations of a phone number by doing semantic checks
on the number you submit. This can help you normalise and consistently
print numbers in your user interface and gives you information to help
you decide if a phone number accept the phone number entered by your
user, or ask them to check and correct it.
Number Insight Basic API is a free synchronous, easy-to-use RESTful web service. For any phone number you can
- Retrieve the international and local format.
- Know the country where the number is registered.
### Example
Request:
```
curl -X POST \
https://api-prd.kpn.com/communication/nexmo/number-insight/basic \
-H 'authorization: Bearer ZvV84AtjcXoHU48hA6b5AZljegdy' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'number=447700900000'
```
Response:
```
{
"status": 0,
"status_message": "Success",
"request_id": "fcb1e9a2-db9c-4ea2-84be-4e60da45e187",
"international_format_number": "447700900000",
"national_format_number": "07700 900000",
"country_code": "GB",
"country_code_iso3": "GBR",
"country_name": "United Kingdom",
"country_prefix": "44"
}
```
consumes:
- application/x-www-form-urlencoded
produces:
- application
parameters:
- in: path
name: level
description: >-
The level of request you wish to make.
enum: ['basic','standard','advanced']
required: true
type: string
- in: formData
name: number
description: >-
The single phone number that you need insight about in national or international format.
example: 447700900000
pattern: '^[0-9-+\(\)\s]*$'
required: true
type: string
- in: formData
name: country
description: >-
If a number does not have a country code or is uncertain, set the two-character country code. This code must be in ISO 3166-1 alpha-2 format and in upper case. For example, GB or US. If you set country and number is already in [E.164](https://en.wikipedia.org/wiki/E.164) format, country must match the country code in number.
example: GB
pattern: '[A-Z]{2}'
required: false
type: string
- in: formData
name: cnam
description: >-
Indicates if the name of the person who owns the phone number should be looked up and returned in the response. Set to true to receive phone number owner name in the response. This features is available for US numbers only and incurs an additional charge.
example: true
required: false
type: boolean
- in: formData
name: ip
description: >-
The IP address of the user. If supplied, we will compare this to the country the user's phone is located in and return an error if it does not match.
example: 123.0.0.255
required: false
type: string
responses:
'200':
description: OK
schema:
$ref: '#/definitions/niResponseBasic'
'400':
description: Bad Request
schema:
$ref: '#/definitions/ErrorResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ErrorResponse'
'404':
description: Not Found
schema:
$ref: '#/definitions/ErrorResponse'
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/ErrorResponse'
'500':
description: Server Error
schema:
$ref: '#/definitions/ErrorResponse'
'503':
description: Service Unavailable
schema:
$ref: '#/definitions/ErrorResponse'
security:
- OAuth2: []
'/advanced/async':
post:
summary: Asynchronously get information about a phone number
tags:
- Request
description: |-
**Number Insight Advanced Async**
You can use Vonage's Number Insight Async API to retrieve a user's landline or mobile number, including checking to see that it is registered to an operator. This can help you verify that a phone number is real and give you information on how to format the number.
Number Insight Advanced Async API is an asynchronous web service that returns data to a webhook. For any phone number you can
- Retrieve the international and local format.
- Know the country where the number is registered.
- Line type detection (mobile/landline/virtual number/premium/toll-free)
- Detect mobile country code (MCC) and mobile network code (MNC)
- Detect if number is ported
- Identify caller name (USA only)
- Identify network when roaming
- Confirm user's IP address is in same location as their mobile phone
Users are advised that the Advanced API does not give any information about landlines that is not already given by the Standard API. For number insights about landlines, you should use the Standard API.
### Example
Request:
```
curl -X POST \
https://api-prd.kpn.com/communication/nexmo/number-insight/advanced/async \
-H 'authorization: Bearer ZvV84AtjcXoHU48hA6b5AZljegdy' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'number=31620028461'
-d 'callback=https://example.com/callback'
```
Response:
```
{
"request_id": "c510011c-d782-4f49-bfa9-38a2254884e4",
"number": "447700900000",
"remaining_balance": "10.000000",
"request_price": "0.03000000",
"status": 0
}
```
consumes:
- application/x-www-form-urlencoded
produces:
- application
parameters:
- in: formData
name: number
description: >-
The single phone number that you need insight about in national or international format.
example: 447700900000
pattern: '^[0-9-+\(\)\s]*$'
required: true
type: string
- in: formData
name: callback
description: >-
The callback URL
example: https://example.com/callback
required: true
type: string
- in: formData
name: country
description: >-
If a number does not have a country code or is uncertain, set the two-character country code. This code must be in ISO 3166-1 alpha-2 format and in upper case. For example, GB or US. If you set country and number is already in [E.164](https://en.wikipedia.org/wiki/E.164) format, country must match the country code in number.
example: GB
pattern: '[A-Z]{2}'
required: false
type: string
- in: formData
name: cnam
description: >-
Indicates if the name of the person who owns the phone number should be looked up and returned in the response. Set to true to receive phone number owner name in the response. This features is available for US numbers only and incurs an additional charge.
example: true
required: false
type: boolean
- in: formData
name: ip
description: >-
The IP address of the user. If supplied, we will compare this to the country the user's phone is located in and return an error if it does not match.
example: 123.0.0.255
required: false
type: string
responses:
'200':
description: OK
schema:
$ref: '#/definitions/niResponseAsync'
'400':
description: Bad Request
schema:
$ref: '#/definitions/ErrorResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ErrorResponse'
'404':
description: Not Found
schema:
$ref: '#/definitions/ErrorResponse'
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/ErrorResponse'
'500':
description: Server Error
schema:
$ref: '#/definitions/ErrorResponse'
'503':
description: Service Unavailable
schema:
$ref: '#/definitions/ErrorResponse'
security:
- OAuth2: []
securityDefinitions:
OAuth2:
type: oauth2
tokenUrl: >-
https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials
flow: application
definitions:
niResponseBasic:
type: object
description: Basic
properties:
status:
$ref: '#/definitions/niStatus'
status_message:
type: string
description: 'The status description of your request.'
example: 'Success'
request_id:
type: string
description: 'The unique identifier for your request. This is a alphanumeric string up to 40 characters.'
example: 'aaaaaaaa-bbbb-cccc-dddd-0123456789ab'
maxLength: 40
international_format_number:
type: string
description: "The `number` in your request in international format."
example: "447700900000"
national_format_number:
type: string
description: "The `number` in your request in the format used by the country the number belongs to."
example: "07700 900000"
country_code:
type: string
description: 'Two character country code for `number`. This is in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.'
example: "GB"
pattern: '[A-Z]{2}'
country_code_iso3:
type: string
description: 'Three character country code for `number`. This is in [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) format.'
example: "GBR"
pattern: '[A-Z]{3}'
country_name:
type: string
description: 'The full name of the country that `number` is registered in.'
example: "United Kingdom"
country_prefix:
type: string
description: 'The numeric prefix for the country that `number` is registered in.'
example: '44'
niResponseStandard:
type: object
description: Standard
properties:
status:
$ref: '#/definitions/niStatus'
status_message:
type: string
description: 'The status description of your request.'
example: 'Success'
request_id:
type: string
description: 'The unique identifier for your request. This is a alphanumeric string up to 40 characters.'
example: 'aaaaaaaa-bbbb-cccc-dddd-0123456789ab'
maxLength: 40
international_format_number:
type: string
description: "The `number` in your request in international format."
example: "447700900000"
national_format_number:
type: string
description: "The `number` in your request in the format used by the country the number belongs to."
example: "07700 900000"
country_code:
type: string
description: 'Two character country code for `number`. This is in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.'
example: "GB"
pattern: '[A-Z]{2}'
country_code_iso3:
type: string
description: 'Three character country code for `number`. This is in [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) format.'
example: "GBR"
pattern: '[A-Z]{3}'
country_name:
type: string
description: 'The full name of the country that `number` is registered in.'
example: "United Kingdom"
country_prefix:
type: string
description: 'The numeric prefix for the country that `number` is registered in.'
example: '44'
request_price:
type: number
description: 'The amount in EUR charged to your account.'
example: "0.04000000"
refund_price:
type: number
description: 'If there is an internal lookup error, the `refund_price` will reflect the lookup price. If `cnam` is requested for a non-US number the `refund_price` will reflect the `cnam` price. If both of these conditions occur, `refund_price` is the sum of the lookup price and `cnam` price.'
example: '0.01500000'
remaining_balance:
type: number
description: 'Your account balance in EUR after this request. Not returned with Number Insight Advanced Async API.'
example: '1.23456789'
current_carrier:
$ref: '#/definitions/niCarrier'
original_carrier:
$ref: '#/definitions/niCarrier'
ported:
type: string
description: 'If the user has changed carrier for `number`. The assumed status means that the information supplier has replied to the request but has not said explicitly that the number is ported.'
enum:
- unknown
- ported
- not_ported
- assumed_not_ported
- assumed_ported
example: 'not_ported'
roaming:
$ref: '#/definitions/niRoaming'
caller_identity:
$ref: '#/definitions/niCallerIdentity'
caller_name:
type: string
description: 'Full name of the person or business who owns the phone number. `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.'
example: 'John Smith'
last_name:
type: string
description: 'Last name of the person who owns the phone number if the owner is an individual. This parameter is only present if `cnam` had a value of `true` within the request.'
example: 'Smith'
first_name:
type: string
description: 'First name of the person who owns the phone number if the owner is an individual. This parameter is only present if `cnam` had a value of `true` within the request.'
example: 'John'
caller_type:
type: string
description: 'The value will be `business` if the owner of a phone number is a business. If the owner is an individual the value will be `consumer`. The value will be `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.'
enum:
- business
- consumer
- unknown
example: 'consumer'
niResponseAdvanced:
type: object
description: Advanced
properties:
status:
$ref: '#/definitions/niStatus'
status_message:
type: string
description: 'The status description of your request.'
example: 'Success'
request_id:
type: string
description: 'The unique identifier for your request. This is a alphanumeric string up to 40 characters.'
example: 'aaaaaaaa-bbbb-cccc-dddd-0123456789ab'
maxLength: 40
international_format_number:
type: string
description: "The `number` in your request in international format."
example: "447700900000"
national_format_number:
type: string
description: "The `number` in your request in the format used by the country the number belongs to."
example: "07700 900000"
country_code:
type: string
description: 'Two character country code for `number`. This is in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.'
example: "GB"
pattern: '[A-Z]{2}'
country_code_iso3:
type: string
description: 'Three character country code for `number`. This is in [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) format.'
example: "GBR"
pattern: '[A-Z]{3}'
country_name:
type: string
description: 'The full name of the country that `number` is registered in.'
example: "United Kingdom"
country_prefix:
type: string
description: 'The numeric prefix for the country that `number` is registered in.'
example: '44'
request_price:
type: number
description: 'The amount in EUR charged to your account.'
example: "0.04000000"
refund_price:
type: number
description: 'If there is an internal lookup error, the `refund_price` will reflect the lookup price. If `cnam` is requested for a non-US number the `refund_price` will reflect the `cnam` price. If both of these conditions occur, `refund_price` is the sum of the lookup price and `cnam` price.'
example: '0.01500000'
remaining_balance:
type: number
description: 'Your account balance in EUR after this request. Not returned with Number Insight Advanced Async API.'
example: '1.23456789'
current_carrier:
$ref: '#/definitions/niCarrier'
original_carrier:
$ref: '#/definitions/niCarrier'
ported:
type: string
description: 'If the user has changed carrier for `number`. The assumed status means that the information supplier has replied to the request but has not said explicitly that the number is ported.'
enum:
- unknown
- ported
- not_ported
- assumed_not_ported
- assumed_ported
example: 'not_ported'
roaming:
$ref: '#/definitions/niRoaming'
caller_identity:
$ref: '#/definitions/niCallerIdentity'
caller_name:
type: string
description: 'Full name of the person or business who owns the phone number. `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.'
example: 'John Smith'
last_name:
type: string
description: 'Last name of the person who owns the phone number if the owner is an individual. This parameter is only present if `cnam` had a value of `true` within the request.'
example: 'Smith'
first_name:
type: string
description: 'First name of the person who owns the phone number if the owner is an individual. This parameter is only present if `cnam` had a value of `true` within the request.'
example: 'John'
caller_type:
type: string
description: 'The value will be `business` if the owner of a phone number is a business. If the owner is an individual the value will be `consumer`. The value will be `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.'
enum:
- business
- consumer
- unknown
example: 'consumer'
lookup_outcome:
type: integer
description: |
Shows if all information about a phone number has been returned. Possible values:
Code | Text
--- | ---
0 | Success
1 | Partial success - some fields populated
2 | Failed
enum:
- 0
- 1
- 2
example: '0'
lookup_outcome_message:
type: string
description: 'Shows if all information about a phone number has been returned.'
example: 'Success'
valid_number:
type: string
description: 'Does `number` exist. This is applicable to mobile numbers only.'
enum:
- unknown
- valid
- not_valid
example: 'valid'
reachable:
type: string
description: 'Can you call `number` now. This is applicable to mobile numbers only.'
enum:
- unknown
- reachable
- undeliverable
- absent
- bad_number
- blacklisted
example: 'reachable'
ip:
$ref: '#/definitions/niIP'
ip_warnings:
type: string
description: 'Warning levels for `ip`'
enum:
- unknown
- no_warning
example: 'no_warning'
required:
- status
- status_message
- request_id
- international_format_number
- national_format_number
- country_code
- country_code_iso3
- country_name
- country_prefix
niCarrier:
type: object
description: 'Information about the network `number` was initially connected to.'
properties:
network_code:
type: string
description: 'The [https://en.wikipedia.org/wiki/Mobile_country_code](https://en.wikipedia.org/wiki/Mobile_country_code) for the carrier`number` is associated with. Unreal numbers are marked as`unknown` and the request is rejected altogether if the number is impossible according to the [E.164](https://en.wikipedia.org/wiki/E.164) guidelines.'
example: '12345'
name:
type: string
description: 'The full name of the carrier that `number` is associated with.'
example: 'Acme Inc'
country:
type: string
description: 'The country that `number` is associated with. This is in ISO 3166-1 alpha-2 format.'
example: 'GB'
network_type:
type: string
description: 'The type of network that `number` is associated with.'
enum:
- mobile
- landline
- landline_premium
- landline_tollfree
- virtual
- unknown
- pager
example: 'mobile'
niRoaming:
type: object
description: 'Information about the network `number` is currently connected to.'
properties:
status:
type: string
description: 'Is `number` outside its home carrier network.'
enum:
- unknown
- roaming
- not_roaming
example: roaming
roaming_country_code:
type: string
description: 'If `number` is `roaming`, this is the [code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the country `number` is roaming in.'
example: US
roaming_network_code:
type: string
description: 'If `number` is `roaming`, this is the id of the carrier network `number` is roaming in.'
example: 12345
roaming_network_name:
type: string
description: 'If `number` is `roaming`, this is the name of the carrier network `number` is roaming in.'
example: 'Acme Inc'
niIP:
type: object
description: 'Information about the provided IP address'
properties:
address:
type: string
description: 'The ip address you specified in the request.'
example: '123.0.0.255'
ip_match_level:
type: string
description: 'The match status between ip and number parameters.'
enum:
- 'country'
- 'mismatch'
example: 'country'
ip_country:
type: string
description: 'The country that `ip` is allocated to.'
example: 'GB'
ip_city:
type: string
description: 'The city that `ip` is allocated to.'
example: 'London'
niCallerIdentity:
type: object
description: 'Information about the network `number` is currently connected to.'
properties:
caller_type:
type: string
description: 'The value will be `business` if the owner of a phone number is a business. If the owner is an individual the value will be `consumer`. The value will be `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.'
enum:
- business
- consumer
- unknown
example: 'consumer'
caller_name:
type: string
description: 'Full name of the person or business who owns the phone number. `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.'
example: 'John Smith'
first_name:
type: string
description: 'First name of the person who owns the phone number if the owner is an individual. This parameter is only present if `cnam` had a value of `true` within the request.'
example: 'John'
last_name:
type: string
description: 'Last name of the person who owns the phone number if the owner is an individual. This parameter is only present if `cnam` had a value of `true` within the request.'
example: 'Smith'
subscription_type:
type: string
# @TODO: description: ''
example: 'unknown'
niStatus:
type: integer
example: 0
enum:
- 0
- 1
- 3
- 4
- 5
- 9
- 19
- 43
- 44
- 45
- 999
description: |
Code | Text
-- | --
0 | Success - request accepted for delivery by Vonage.
1 | Busy - you have made more requests in the last second than are permitted by your Vonage account. Please retry.
3 | Invalid - your request is incomplete and missing some mandatory parameters.
4 | Invalid credentials - the _api_key_ or _api_secret_ you supplied is either not valid or has been disabled.
5 | Internal Error - the format of the recipient address is not valid.
9 | Partner quota exceeded - your Vonage account does not have sufficient credit to process this request.
#### Standard and Advanced only
Code | Text
-- | --
19 | Facility Not Allowed - your request makes use of a facility that is not enabled on your account.
43, 44, 45 | Live mobile lookup not returned. Not all return parameters are available.
999 | Request unparseable.
niResponseAsync:
type: object
properties:
request_id:
type: string
description: 'The unique identifier for your request. This is a alphanumeric string up to 40 characters.'
example: 'aaaaaaaa-bbbb-cccc-dddd-0123456789ab'
maxLength: 40
number:
type: string
description: "The `number` in your request"
example: '447700900000'
remaining_balance:
type: string
description: 'Your account balance in EUR after this request. Not returned with Number Insight Advanced Async API.'
example: '1.23456789'
request_price:
type: number
description: 'If there is an internal lookup error, the `refund_price` will reflect the lookup price. If `cnam` is requested for a non-US number the `refund_price` will reflect the `cnam` price. If both of these conditions occur, `refund_price` is the sum of the lookup price and `cnam` price.'
example: '0.01500000'
status:
$ref: '#/definitions/niStatus'
ErrorResponse:
type: object
properties:
transactionId:
type: string
description: transaction id of the the request
title: Transaction ID
status:
type: string
description: Status
title: Status
name:
type: string
description: Error name
title: Error name
message:
type: string
description: Error message
title: Error message
info:
type: string
description: Additional information about error
title: Info