Number Insight API

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. The advanced API is available asynchronously as well as synchronously.

To detect SIM Swap, obtain carrier information, and validate phone number format, please migrate to the new Identity Insights API.

OpenAPI-Spezifikation herunterladen

Verfügbare Operationen

Basic Number Insight

Provides basic number insight information about a number.

Note that this endpoint also supports POST requests.

gethttps://api.nexmo.com/ni/basic/:format

Authentifizierung

Schlüssel	Beschreibung	Wo	Beispiel
api_key	You can find your API key in your account overview	query	`?api_key=<api_key>`
api_secret	You can find your API secret in your account overview	query	`?api_secret=<api_secret>`

Pfad Parameter

format

string

Erforderlich

The format of the response

Muss eines der folgenden sein:jsonxml

Abfrage Parameter

number

string

A single phone number that you need insight about in national or international format.

country

string

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 format, country must match the country code in number.

Antworten
Inhalt Typ
application/json

status

integer

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.

Muss eines der folgenden sein:013459

status_message

string

BeispielSuccess

The status description of your request.

request_id

string

Max40

Beispielaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The unique identifier for your request. This is a alphanumeric string up to 40 characters.

international_format_number

string

Beispiel447700900000

The number in your request in international format.

national_format_number

string

Beispiel07700 900000

The number in your request in the format used by the country the number belongs to.

country_code

string

BeispielGB

Two character country code for number. This is in ISO 3166-1 alpha-2 format.

country_code_iso3

string

BeispielGBR

Three character country code for number. This is in ISO 3166-1 alpha-3 format.

country_name

string

BeispielUnited Kingdom

The full name of the country that number is registered in.

country_prefix

string

Beispiel44

The numeric prefix for the country that number is registered in.

Beispiel Antwort

{
   "status": 0,
   "status_message": "Success",
   "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "international_format_number": "447700900000",
   "national_format_number": "07700 900000",
   "country_code": "GB",
   "country_code_iso3": "GBR",
   "country_name": "United Kingdom",
   "country_prefix": "44"
}

Standard Number Insight

Provides standard number insight information about a number.

Note that this endpoint also supports POST requests.

gethttps://api.nexmo.com/ni/standard/:format

Authentifizierung

Schlüssel	Beschreibung	Wo	Beispiel
api_key	You can find your API key in your account overview	query	`?api_key=<api_key>`
api_secret	You can find your API secret in your account overview	query	`?api_secret=<api_secret>`

Pfad Parameter

format

string

Erforderlich

The format of the response

Muss eines der folgenden sein:jsonxml

Abfrage Parameter

number

string

A single phone number that you need insight about in national or international format.

country

string

cnam

boolean

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.

Antworten
Inhalt Typ
application/json

Einer der

status

integer

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.

Muss eines der folgenden sein:013459

status_message

string

BeispielSuccess

The status description of your request.

request_id

string

Max40

Beispielaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The unique identifier for your request. This is a alphanumeric string up to 40 characters.

international_format_number

string

Beispiel447700900000

The number in your request in international format.

national_format_number

string

Beispiel07700 900000

The number in your request in the format used by the country the number belongs to.

country_code

string

BeispielGB

Two character country code for number. This is in ISO 3166-1 alpha-2 format.

country_code_iso3

string

BeispielGBR

Three character country code for number. This is in ISO 3166-1 alpha-3 format.

country_name

string

BeispielUnited Kingdom

The full name of the country that number is registered in.

country_prefix

string

Beispiel44

The numeric prefix for the country that number is registered in.

request_price

string

Beispiel0.04000000

The amount in EUR charged to your account.

refund_price

string

Beispiel0.01500000

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.

remaining_balance

string

Beispiel1.23456789

Your account balance in EUR after this request.

current_carrier

object

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.

network_code

string

Beispiel12345

The https://en.wikipedia.org/wiki/Mobile_country_code for the carriernumber is associated with. Unreal numbers are marked asnull and the request is rejected altogether if the number is impossible according to the E.164 guidelines.

name

string

BeispielAcme Inc

The full name of the carrier that number is associated with.

country

string

BeispielGB

The country that number is associated with. This is in ISO 3166-1 alpha-2 format.

network_type

string

Beispielmobile

The type of network that number is associated with.

Muss eines der folgenden sein:mobilelandlinelandline_premiumlandline_tollfreevirtualunknownpagernull

original_carrier

object

Information about the network number was initially connected to.

network_code

string

Beispiel12345

name

string

BeispielAcme Inc

The full name of the carrier that number is associated with.

country

string

BeispielGB

The country that number is associated with. This is in ISO 3166-1 alpha-2 format.

network_type

string

Beispielmobile

The type of network that number is associated with.

Muss eines der folgenden sein:mobilelandlinelandline_premiumlandline_tollfreevirtualunknownpagernull

ported

string

Beispielnot_ported

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.

Muss eines der folgenden sein:unknownportednot_portedassumed_not_portedassumed_portednull

caller_identity

object

Information about the network number is currently connected to.

caller_type

string

Beispielconsumer

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.

Muss eines der folgenden sein:businessconsumerunknown

caller_name

string

BeispielJohn Smith

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.

first_name

string

BeispielJohn

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.

last_name

string

BeispielSmith

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.

caller_name

string

BeispielJohn Smith

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.

last_name

string

BeispielSmith

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.

first_name

string

BeispielJohn

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.

caller_type

string

Beispielconsumer

Muss eines der folgenden sein:businessconsumerunknown

Beispiel Antwort»Standard Response

{
   "status": 0,
   "status_message": "Success",
   "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "international_format_number": "447700900000",
   "national_format_number": "07700 900000",
   "country_code": "GB",
   "country_code_iso3": "GBR",
   "country_name": "United Kingdom",
   "country_prefix": "44",
   "request_price": "0.04000000",
   "refund_price": "0.01500000",
   "remaining_balance": "1.23456789",
   "current_carrier": {
      "network_code": "12345",
      "name": "Acme Inc",
      "country": "GB",
      "network_type": "mobile"
   },
   "original_carrier": {
      "network_code": "12345",
      "name": "Acme Inc",
      "country": "GB",
      "network_type": "mobile"
   },
   "ported": "not_ported",
   "caller_identity": {
      "caller_type": "consumer",
      "caller_name": "John Smith",
      "first_name": "John",
      "last_name": "Smith"
   },
   "caller_name": "John Smith",
   "last_name": "Smith",
   "first_name": "John",
   "caller_type": "consumer"
}

Advanced Number Insight (async)

Provides advanced number insight 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.

gethttps://api.nexmo.com/ni/advanced/async/:format

Authentifizierung

Schlüssel	Beschreibung	Wo	Beispiel
api_key	You can find your API key in your account overview	query	`?api_key=<api_key>`
api_secret	You can find your API secret in your account overview	query	`?api_secret=<api_secret>`

Pfad Parameter

format

string

Erforderlich

The format of the response

Muss eines der folgenden sein:jsonxml

Abfrage Parameter

callback

string(uriref)

The callback URL

number

string

A single phone number that you need insight about in national or international format.

country

string

cnam

boolean

string

This parameter is deprecated as we are no longer able to retrieve reliable IP data globally from carriers.

Antworten
Inhalt Typ
application/json

Einer der

request_id

string

Max40

Beispielaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The unique identifier for your request. This is a alphanumeric string up to 40 characters.

number

string

Beispiel447700900000

The number in your request

remaining_balance

string

Beispiel1.23456789

Your account balance in EUR after this request.

request_price

string

Beispiel0.01500000

status

integer

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.

Muss eines der folgenden sein:01345919434445999

error_text

string

BeispielSuccess

The status description of your request. Note: This field is equivalent to status_message field in the other endpoints

Beispiel Antwort»Async Response

{
   "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "number": "447700900000",
   "remaining_balance": "1.23456789",
   "request_price": "0.01500000",
   "status": 0,
   "error_text": "Success"
}

Advanced Number Insight (sync)

Provides advanced number insight 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.

gethttps://api.nexmo.com/ni/advanced/:format

Authentifizierung

Schlüssel	Beschreibung	Wo	Beispiel
api_key	You can find your API key in your account overview	query	`?api_key=<api_key>`
api_secret	You can find your API secret in your account overview	query	`?api_secret=<api_secret>`

Pfad Parameter

format

string

Erforderlich

The format of the response

Muss eines der folgenden sein:jsonxml

Abfrage Parameter

real_time_data

boolean

[This parameter is deprecated] Real time data about the number. This is applicable to mobile numbers only.

number

string

A single phone number that you need insight about in national or international format.

country

string

cnam

boolean

string

This parameter is deprecated as we are no longer able to retrieve reliable IP data globally from carriers.

Antworten
Inhalt Typ
application/json

Einer der

status

integer

Erforderlich

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.

Muss eines der folgenden sein:01345919434445999

status_message

string

Erforderlich

BeispielSuccess

The status description of your request.

request_id

string

Erforderlich

Max40

Beispielaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The unique identifier for your request. This is a alphanumeric string up to 40 characters.

international_format_number

string

Erforderlich

Beispiel447700900000

The number in your request in international format.

national_format_number

string

Erforderlich

Beispiel07700 900000

The number in your request in the format used by the country the number belongs to.

country_code

string

Erforderlich

BeispielGB

Two character country code for number. This is in ISO 3166-1 alpha-2 format.

country_code_iso3

string

Erforderlich

BeispielGBR

Three character country code for number. This is in ISO 3166-1 alpha-3 format.

country_name

string

Erforderlich

BeispielUnited Kingdom

The full name of the country that number is registered in.

country_prefix

string

Erforderlich

Beispiel44

The numeric prefix for the country that number is registered in.

request_price

string

Beispiel0.04000000

The amount in EUR charged to your account.

refund_price

string

Beispiel0.01500000

remaining_balance

string

Beispiel1.23456789

Your account balance in EUR after this request.

current_carrier

object

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.

network_code

string

Beispiel12345

name

string

BeispielAcme Inc

The full name of the carrier that number is associated with.

country

string

BeispielGB

The country that number is associated with. This is in ISO 3166-1 alpha-2 format.

network_type

string

Beispielmobile

The type of network that number is associated with.

Muss eines der folgenden sein:mobilelandlinelandline_premiumlandline_tollfreevirtualunknownpagernull

original_carrier

object

Information about the network number was initially connected to.

network_code

string

Beispiel12345

name

string

BeispielAcme Inc

The full name of the carrier that number is associated with.

country

string

BeispielGB

The country that number is associated with. This is in ISO 3166-1 alpha-2 format.

network_type

string

Beispielmobile

The type of network that number is associated with.

Muss eines der folgenden sein:mobilelandlinelandline_premiumlandline_tollfreevirtualunknownpagernull

ported

string

Beispielnot_ported

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.

Muss eines der folgenden sein:unknownportednot_portedassumed_not_portedassumed_portednull

roaming

object

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.

status

string

Beispielroaming

Is number outside its home carrier network.

Muss eines der folgenden sein:roamingnot_roaming

roaming_country_code

string

BeispielUS

If number is roaming, this is the code of the country number is roaming in.

roaming_network_code

string

Beispiel12345

If number is roaming, this is the id of the carrier network number is roaming in.

roaming_network_name

string

BeispielAcme Inc

If number is roaming, this is the name of the carrier network number is roaming in.

caller_identity

object

Information about the network number is currently connected to.

caller_type

string

Beispielconsumer

Muss eines der folgenden sein:businessconsumerunknown

caller_name

string

BeispielJohn Smith

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.

first_name

string

BeispielJohn

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.

last_name

string

BeispielSmith

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.

lookup_outcome

integer

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

Muss eines der folgenden sein:012

lookup_outcome_message

string

BeispielSuccess

Shows if all information about a phone number has been returned.

valid_number

string

Beispielvalid

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.

Muss eines der folgenden sein:unknownvalidnot_validinferredinferred_not_valid

reachable

string

Beispielreachable

Can you call number now. This is applicable to mobile numbers only.

Muss eines der folgenden sein:unknownreachableundeliverableabsentbad_numberblacklistednull

real_time_data

object

[This parameter is deprecated] Real time data about the number

active_status

string

Beispielinactive

[This parameter is deprecated. If requested it returns always inactive]. Whether the end-user's phone number is assigned to an operator's network. Can be active, inactive or null.

handset_status

string

Beispieloff

[This parameter is deprecated. If requested it returns always off]. Whether the end-user's handset is reachable. Can be on if reachable or off if not reachable.

Beispiel Antwort»Advanced Response (sync)

{
   "status": 0,
   "status_message": "Success",
   "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "international_format_number": "447700900000",
   "national_format_number": "07700 900000",
   "country_code": "GB",
   "country_code_iso3": "GBR",
   "country_name": "United Kingdom",
   "country_prefix": "44",
   "request_price": "0.04000000",
   "refund_price": "0.01500000",
   "remaining_balance": "1.23456789",
   "current_carrier": {
      "network_code": "12345",
      "name": "Acme Inc",
      "country": "GB",
      "network_type": "mobile"
   },
   "original_carrier": {
      "network_code": "12345",
      "name": "Acme Inc",
      "country": "GB",
      "network_type": "mobile"
   },
   "ported": "not_ported",
   "roaming": {
      "status": "roaming",
      "roaming_country_code": "US",
      "roaming_network_code": "12345",
      "roaming_network_name": "Acme Inc"
   },
   "caller_identity": {
      "caller_type": "consumer",
      "caller_name": "John Smith",
      "first_name": "John",
      "last_name": "Smith"
   },
   "lookup_outcome": 0,
   "lookup_outcome_message": "Success",
   "valid_number": "valid",
   "reachable": "reachable",
   "real_time_data": {
      "active_status": "inactive",
      "handset_status": "off"
   }
}

Webhaken

Webhooks sind eine Erweiterung einer API, aber anstatt dass Ihr Code Daten anfordert, sendet die API Daten an Sie. Die Daten werden in einer Webanforderung an Ihre Anwendung gesendet.

Um mehr über Webhooks zu erfahren, besuchen Sie unsere Website Webhooks-Dokumentation.

Diese API kann jeden der unten dokumentierten Webhooks an die von Ihnen konfigurierte URL senden. Sie müssen mit einer 200 oder 204 HTTP-Antwort antworten, andernfalls werden die Anfragen erneut versucht.

Verfügbare Operationen

Asynchronous response webhook

posthttps://example.com/webhooks/event

Anfrage Körper
Inhalt Typ
application/json

status

integer

Erforderlich

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.

Muss eines der folgenden sein:01345919434445999

status_message

string

Erforderlich

BeispielSuccess

The status description of your request.

request_id

string

Erforderlich

Max40

Beispielaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The unique identifier for your request. This is a alphanumeric string up to 40 characters.

international_format_number

string

Erforderlich

Beispiel447700900000

The number in your request in international format.

national_format_number

string

Erforderlich

Beispiel07700 900000

The number in your request in the format used by the country the number belongs to.

country_code

string

Erforderlich

BeispielGB

Two character country code for number. This is in ISO 3166-1 alpha-2 format.

country_code_iso3

string

Erforderlich

BeispielGBR

Three character country code for number. This is in ISO 3166-1 alpha-3 format.

country_name

string

Erforderlich

BeispielUnited Kingdom

The full name of the country that number is registered in.

country_prefix

string

Erforderlich

Beispiel44

The numeric prefix for the country that number is registered in.

request_price

string

Beispiel0.04000000

The amount in EUR charged to your account.

refund_price

string

Beispiel0.01500000

remaining_balance

string

Beispiel1.23456789

Your account balance in EUR after this request.

current_carrier

object

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.

network_code

string

Beispiel12345

name

string

BeispielAcme Inc

The full name of the carrier that number is associated with.

country

string

BeispielGB

The country that number is associated with. This is in ISO 3166-1 alpha-2 format.

network_type

string

Beispielmobile

The type of network that number is associated with.

Muss eines der folgenden sein:mobilelandlinelandline_premiumlandline_tollfreevirtualunknownpagernull

original_carrier

object

Information about the network number was initially connected to.

network_code

string

Beispiel12345

name

string

BeispielAcme Inc

The full name of the carrier that number is associated with.

country

string

BeispielGB

The country that number is associated with. This is in ISO 3166-1 alpha-2 format.

network_type

string

Beispielmobile

The type of network that number is associated with.

Muss eines der folgenden sein:mobilelandlinelandline_premiumlandline_tollfreevirtualunknownpagernull

ported

string

Beispielnot_ported

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.

Muss eines der folgenden sein:unknownportednot_portedassumed_not_portedassumed_portednull

roaming

object

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.

status

string

Beispielroaming

Is number outside its home carrier network.

Muss eines der folgenden sein:roamingnot_roaming

roaming_country_code

string

BeispielUS

If number is roaming, this is the code of the country number is roaming in.

roaming_network_code

string

Beispiel12345

If number is roaming, this is the id of the carrier network number is roaming in.

roaming_network_name

string

BeispielAcme Inc

If number is roaming, this is the name of the carrier network number is roaming in.

caller_identity

object

Information about the network number is currently connected to.

caller_type

string

Beispielconsumer

Muss eines der folgenden sein:businessconsumerunknown

caller_name

string

BeispielJohn Smith

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.

first_name

string

BeispielJohn

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.

last_name

string

BeispielSmith

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.

lookup_outcome

integer

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

Muss eines der folgenden sein:012

lookup_outcome_message

string

BeispielSuccess

Shows if all information about a phone number has been returned.

valid_number

string

Beispielvalid

Muss eines der folgenden sein:unknownvalidnot_validinferredinferred_not_valid

reachable

string

Beispielreachable

Can you call number now. This is applicable to mobile numbers only.

Muss eines der folgenden sein:unknownreachableundeliverableabsentbad_numberblacklistednull

Beispiel Nutzlast

{
   "status": 0,
   "status_message": "Success",
   "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "international_format_number": "447700900000",
   "national_format_number": "07700 900000",
   "country_code": "GB",
   "country_code_iso3": "GBR",
   "country_name": "United Kingdom",
   "country_prefix": "44",
   "request_price": "0.04000000",
   "refund_price": "0.01500000",
   "remaining_balance": "1.23456789",
   "current_carrier": {
      "network_code": "12345",
      "name": "Acme Inc",
      "country": "GB",
      "network_type": "mobile"
   },
   "original_carrier": {
      "network_code": "12345",
      "name": "Acme Inc",
      "country": "GB",
      "network_type": "mobile"
   },
   "ported": "not_ported",
   "roaming": {
      "status": "roaming",
      "roaming_country_code": "US",
      "roaming_network_code": "12345",
      "roaming_network_name": "Acme Inc"
   },
   "caller_identity": {
      "caller_type": "consumer",
      "caller_name": "John Smith",
      "first_name": "John",
      "last_name": "Smith"
   },
   "lookup_outcome": 0,
   "lookup_outcome_message": "Success",
   "valid_number": "valid",
   "reachable": "reachable"
}

Antworten

Asynchronous response with Unknown Roaming webhook

Contains the response to your Number Insight Advanced API request.

posthttps://example.com/webhooks/event

Anfrage Körper
Inhalt Typ
application/json

status

integer

Erforderlich

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.

Muss eines der folgenden sein:01345919434445999

status_message

string

Erforderlich

BeispielSuccess

The status description of your request.

request_id

string

Erforderlich

Max40

Beispielaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The unique identifier for your request. This is a alphanumeric string up to 40 characters.

international_format_number

string

Erforderlich

Beispiel447700900000

The number in your request in international format.

national_format_number

string

Erforderlich

Beispiel07700 900000

The number in your request in the format used by the country the number belongs to.

country_code

string

Erforderlich

BeispielGB

Two character country code for number. This is in ISO 3166-1 alpha-2 format.

country_code_iso3

string

Erforderlich

BeispielGBR

Three character country code for number. This is in ISO 3166-1 alpha-3 format.

country_name

string

Erforderlich

BeispielUnited Kingdom

The full name of the country that number is registered in.

country_prefix

string

Erforderlich

Beispiel44

The numeric prefix for the country that number is registered in.

request_price

string

Beispiel0.04000000

The amount in EUR charged to your account.

refund_price

string

Beispiel0.01500000

remaining_balance

string

Beispiel1.23456789

Your account balance in EUR after this request.

current_carrier

object

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.

network_code

string

Beispiel12345

name

string

BeispielAcme Inc

The full name of the carrier that number is associated with.

country

string

BeispielGB

The country that number is associated with. This is in ISO 3166-1 alpha-2 format.

network_type

string

Beispielmobile

The type of network that number is associated with.

Muss eines der folgenden sein:mobilelandlinelandline_premiumlandline_tollfreevirtualunknownpagernull

original_carrier

object

Information about the network number was initially connected to.

network_code

string

Beispiel12345

name

string

BeispielAcme Inc

The full name of the carrier that number is associated with.

country

string

BeispielGB

The country that number is associated with. This is in ISO 3166-1 alpha-2 format.

network_type

string

Beispielmobile

The type of network that number is associated with.

Muss eines der folgenden sein:mobilelandlinelandline_premiumlandline_tollfreevirtualunknownpagernull

ported

string

Beispielnot_ported

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.

Muss eines der folgenden sein:unknownportednot_portedassumed_not_portedassumed_portednull

roaming

string

Beispielunknown

Muss eines der folgenden sein:unknown

caller_identity

object

Information about the network number is currently connected to.

caller_type

string

Beispielconsumer

Muss eines der folgenden sein:businessconsumerunknown

caller_name

string

BeispielJohn Smith

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.

first_name

string

BeispielJohn

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.

last_name

string

BeispielSmith

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.

lookup_outcome

integer

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

Muss eines der folgenden sein:012

lookup_outcome_message

string

BeispielSuccess

Shows if all information about a phone number has been returned.

valid_number

string

Beispielvalid

Muss eines der folgenden sein:unknownvalidnot_validinferredinferred_not_valid

reachable

string

Beispielreachable

Can you call number now. This is applicable to mobile numbers only.

Muss eines der folgenden sein:unknownreachableundeliverableabsentbad_numberblacklistednull

Beispiel Nutzlast

{
   "status": 0,
   "status_message": "Success",
   "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "international_format_number": "447700900000",
   "national_format_number": "07700 900000",
   "country_code": "GB",
   "country_code_iso3": "GBR",
   "country_name": "United Kingdom",
   "country_prefix": "44",
   "request_price": "0.04000000",
   "refund_price": "0.01500000",
   "remaining_balance": "1.23456789",
   "current_carrier": {
      "network_code": "12345",
      "name": "Acme Inc",
      "country": "GB",
      "network_type": "mobile"
   },
   "original_carrier": {
      "network_code": "12345",
      "name": "Acme Inc",
      "country": "GB",
      "network_type": "mobile"
   },
   "ported": "not_ported",
   "roaming": "unknown",
   "caller_identity": {
      "caller_type": "consumer",
      "caller_name": "John Smith",
      "first_name": "John",
      "last_name": "Smith"
   },
   "lookup_outcome": 0,
   "lookup_outcome_message": "Success",
   "valid_number": "valid",
   "reachable": "reachable"
}

Number Insight API

Verfügbare Operationen

Basic Number Insight

Authentifizierung

Pfad Parameter

Abfrage Parameter

Antworten Inhalt Typapplication/json

Beispiel Antwort

Standard Number Insight

Authentifizierung

Pfad Parameter

Abfrage Parameter

Antworten Inhalt Typapplication/json

Beispiel Antwort»Standard Response

Advanced Number Insight (async)

Authentifizierung

Pfad Parameter

Abfrage Parameter

Antworten Inhalt Typapplication/json

Beispiel Antwort»Async Response

Advanced Number Insight (sync)

Authentifizierung

Pfad Parameter

Abfrage Parameter

Antworten Inhalt Typapplication/json

Beispiel Antwort»Advanced Response (sync)

Webhaken

Verfügbare Operationen

Asynchronous response webhook

Anfrage Körper Inhalt Typapplication/json

Beispiel Nutzlast

Antworten

Asynchronous response with Unknown Roaming webhook

Anfrage Körper Inhalt Typapplication/json

Beispiel Nutzlast

Antworten

Antworten
Inhalt Typ
application/json

Antworten
Inhalt Typ
application/json

Antworten
Inhalt Typ
application/json

Antworten
Inhalt Typ
application/json

Anfrage Körper
Inhalt Typ
application/json

Anfrage Körper
Inhalt Typ
application/json