Vonage JWT 2
Documentation / Vonage JWT
This is the Vonage Number Insights SDK for Node.js for use with Vonage APIs. To use it you will need a Vonage account. Sign up for free at vonage.com.
For full API documentation refer to developer.nexmo.com.
If you are updating from V2 to V3, please check the migration guide found here
We recommend using this SDK as part of the overall @vonage/server-sdk package. Please see the main package for installation.
You can also use this SDK standalone if you only need access to just the Messages API.
npm install @vonage/number-insightsyarn add @vonage/number-insightsIf you are using this SDK as part of the Vonage Server SDK, you can access it as the messages property off of the client that you instantiate.
const { Auth } = require('@vonage/auth');
const { Vonage } = require('@vonage/server-sdk');
const credentials = new Auth({
apiKey: API_KEY,
apiSecret: API_SECRET
});
const options = {};
const vonage = new Vonage(credentials, options);
vonage.numberInsights.basicLookup(PHONE_NUMBER)
.then(resp => console.log(resp))
.catch(err => console.error(err));The SDK can be used standalone from the main Vonage Server SDK for Node.js if you only need to use the Messages API. All you need to do is require('@vonage/number-insights'), and use the returned object to create your own client.
const { Auth } = require('@vonage/auth');
const { NumberInsights } = require('@vonage/number-insights');
const credentials = new Auth({
apiKey: API_KEY,
apiSecret: API_SECRET
});
const options = {};
const niClient = new NumberInsights(credentials, options);Where credentials is any option from @vonage/auth, and options is any option from @vonage/server-client
Most methods that interact with the Vonage API uses Promises. You can either resolve these yourself, or use await to wait for a response.
const resp = await vonage.numberInsights.basicLookup(PHONE_NUMBER)
vonage.numberInsights.basicLookup(PHONE_NUMBER)
.then(resp => console.log(resp))
.catch(err => console.error(err));Run:
npm run testDefined in: number-insights/lib/enums/CallerType.ts:4
Enum representing the type of caller for a phone number.
| Enumeration Member | Value | Description | Defined in |
|---|---|---|---|
BUSINESS
|
"business" |
The value will be "business" if the owner of a phone number is a business. | number-insights/lib/enums/CallerType.ts:13 |
CONSUMER
|
"consumer" |
The value will be "consumer" if the owner of a phone number is an individual. | number-insights/lib/enums/CallerType.ts:18 |
UNKNOWN
|
"unknown" |
The value will be "unknown" if the information about the caller type is not available. | number-insights/lib/enums/CallerType.ts:8 |
Defined in: number-insights/lib/enums/LookupOutcome.ts:4
Enum representing the outcomes of a lookup operation.
| Enumeration Member | Value | Description | Defined in |
|---|---|---|---|
FAILED
|
2 |
The lookup operation failed. | number-insights/lib/enums/LookupOutcome.ts:18 |
PARTIAL_SUCCESS
|
1 |
The lookup operation partially succeeded. | number-insights/lib/enums/LookupOutcome.ts:13 |
SUCCESS
|
0 |
The lookup operation was successful. | number-insights/lib/enums/LookupOutcome.ts:8 |
Defined in: number-insights/lib/enums/NetworkType.ts:4
Enum representing the type of network associated with a phone number.
| Enumeration Member | Value | Description | Defined in |
|---|---|---|---|
LANDLINE
|
"landline" |
The phone number is associated with a landline network. | number-insights/lib/enums/NetworkType.ts:13 |
LANDLINE_PREMIUM
|
"landline_premium" |
The phone number is associated with a premium landline network. | number-insights/lib/enums/NetworkType.ts:18 |
LANDLINE_TOLLFREE
|
"landline_tollfree" |
The phone number is associated with a toll-free landline network. | number-insights/lib/enums/NetworkType.ts:23 |
MOBILE
|
"mobile" |
The phone number is associated with a mobile network. | number-insights/lib/enums/NetworkType.ts:8 |
PAGER
|
"pager" |
The phone number is associated with a pager network. | number-insights/lib/enums/NetworkType.ts:38 |
UNKNOWN
|
"unknown" |
The type of network associated with the phone number is unknown. | number-insights/lib/enums/NetworkType.ts:33 |
VIRTUAL
|
"virtual" |
The phone number is associated with a virtual network. | number-insights/lib/enums/NetworkType.ts:28 |
Defined in: number-insights/lib/enums/Reachable.ts:4
Enum representing the reachability status of a phone number.
| Enumeration Member | Value | Description | Defined in |
|---|---|---|---|
ABSENT
|
"absent" |
The phone number's owner is absent. | number-insights/lib/enums/Reachable.ts:23 |
BAD_NUMBER
|
"bad_number" |
The phone number is invalid or a bad number. | number-insights/lib/enums/Reachable.ts:28 |
BLACKLISTED
|
"blacklisted" |
The phone number is blacklisted. | number-insights/lib/enums/Reachable.ts:33 |
REACHABLE
|
"reachable" |
The phone number is reachable. | number-insights/lib/enums/Reachable.ts:13 |
UNDELIVERABLE
|
"undeliverable" |
The phone number is undeliverable. | number-insights/lib/enums/Reachable.ts:18 |
UNKNOWN
|
"unknown" |
The reachability status is unknown. | number-insights/lib/enums/Reachable.ts:8 |
Defined in: number-insights/lib/enums/ValidNumber.ts:4
Enum representing the validity status of a phone number.
| Enumeration Member | Value | Description | Defined in |
|---|---|---|---|
INFERRED
|
"inferred" |
The validity of the phone number is inferred. | number-insights/lib/enums/ValidNumber.ts:23 |
INFERRED_NOT_VALID
|
"inferred_not_valid" |
The inferred validity of the phone number is not valid. | number-insights/lib/enums/ValidNumber.ts:28 |
NOT_VALID
|
"not_valid" |
The phone number is not valid. | number-insights/lib/enums/ValidNumber.ts:18 |
UNKNOWN
|
"unknown" |
The validity status is unknown. | number-insights/lib/enums/ValidNumber.ts:8 |
VALID
|
"valid" |
The phone number is valid. | number-insights/lib/enums/ValidNumber.ts:13 |
Defined in: number-insights/lib/number-insights.ts:41
Client for the Vonage Number Insights API.
Create a standalone Number Insight client
import { NumberInsights } from '@vonage/numberInsight';
const numberInsightClient = new NumberInsights({
apiKey: VONAGE_API_KEY,
apiSecret: VONAGE_API_SECRET
});Create an Number Insight client from the Vonage client
import { Vonage } from '@vonage/server-client';
const vonage = new Vonage({
apiKey: VONAGE_API_KEY,
apiSecret: VONAGE_API_SECRET
});
const numberInsightClient = vonage.numberInsight;new NumberInsights(credentials, options?): NumberInsights;Defined in: server-client/dist/lib/client.d.ts:35
Creates a new instance of the Client.
The authentication credentials or an authentication instance.
Optional configuration settings for the client.
protected auth: AuthInterface;Defined in: server-client/dist/lib/client.d.ts:24
The authentication instance responsible for generating authentication headers and query parameters.
protected authType: AuthenticationType = AuthenticationType.BASIC;Defined in: number-insights/lib/number-insights.ts:45
protected config: ConfigParams;Defined in: server-client/dist/lib/client.d.ts:28
Configuration settings for the client, including default hosts for various services and other request settings.
static transformers: object;Defined in: server-client/dist/lib/client.d.ts:11
Static property containing utility transformers.
camelCaseObjectKeys: PartialTransformFunction;kebabCaseObjectKeys: PartialTransformFunction;omit: (keys, obj) => TransformedObject;string[]
snakeCaseObjectKeys: PartialTransformFunction;addAuthenticationToRequest(request): Promise<VetchOptions>;Defined in: server-client/dist/lib/client.d.ts:43
Adds the appropriate authentication headers or parameters to the request based on the authentication type.
The request options to which authentication needs to be added.
Promise<VetchOptions>
- The request options with the added authentication.
Client.addAuthenticationToRequest
protected addBasicAuthToRequest(request): Promise<VetchOptions>;Defined in: server-client/dist/lib/client.d.ts:71
Adds basic authentication headers to the request.
The request options to which authentication needs to be added.
Promise<VetchOptions>
- The request options with the added authentication.
protected addJWTToRequest(request): Promise<VetchOptions>;Defined in: server-client/dist/lib/client.d.ts:64
Adds a JWT to the request.
The request options to which authentication needs to be added.
Promise<VetchOptions>
- The request options with the added authentication.
protected addQueryKeySecretToRequest(request): Promise<VetchOptions>;Defined in: server-client/dist/lib/client.d.ts:57
Adds API key and secret to the request.
The request options to which authentication needs to be added.
Promise<VetchOptions>
- The request options with the added authentication.
Client.addQueryKeySecretToRequest
protected addQueryKeySecretToRequestBody(request): Promise<VetchOptions>;Defined in: server-client/dist/lib/client.d.ts:50
Adds API key and secret to the request body.
The request options to which authentication needs to be added.
Promise<VetchOptions>
- The request options with the added authentication.
Client.addQueryKeySecretToRequestBody
advancedLookup(phoneNumber, options?): Promise<AdvancedResponse>;Defined in: number-insights/lib/number-insights.ts:60
Perform an advanced number lookup operation.
string
The phone number to perform the lookup for.
Additional options for the lookup.
Promise<AdvancedResponse>
A promise that resolves to the advanced lookup response.
const lookup = await numberInsightsClient.advancedLookup('15555551212');
console.log(`Ths number is ${lookup.valid_number}`);asyncAdvancedLookup(
phoneNumber,
callback,
options?): Promise<AsyncAdvancedResponse>;Defined in: number-insights/lib/number-insights.ts:100
Perform an asynchronous advanced number lookup operation.
string
The phone number to perform the lookup for.
string
The callback URL for receiving the async lookup response.
Additional options for the lookup.
Promise<AsyncAdvancedResponse>
A promise that resolves to the async advanced lookup response.
const lookup = await numberInsightsClient.asyncAdvancedLookup(
'15555551212',
'https://example.com/number-insights',
);
console.log(`The request ID is ${lookup.request_id}`);Lookup with the CNAME option:
const lookup = await numberInsightsClient.asyncAdvancedLookup(
'15555551212',
'https://example.com/number-insights',
{ cname: true },
);
console.log(`The request ID is ${lookup.request_id}`);basicLookup(phoneNumber, options?): Promise<BasicResponse>;Defined in: number-insights/lib/number-insights.ts:138
Perform a basic number lookup operation.
string
The phone number to perform the lookup for.
Additional options for the lookup.
Promise<BasicResponse>
A promise that resolves to the basic lookup response.
const lookup = await numberInsightsClient.basicLookup(
'15555551212',
);
console.log(`The request ID is ${lookup.request_id}`);Lookup with the country option:
const lookup = await numberInsightsClient.basicLookup(
'15555551212',
{ country: 'US' },
);
console.log(`The request ID is ${lookup.request_id}`);getConfig(): ConfigParams;Defined in: server-client/dist/lib/client.d.ts:36
protected parseResponse<T>(request, response): Promise<VetchResponse<T>>;Defined in: server-client/dist/lib/client.d.ts:168
Parses the response based on its content type.
T
The expected type of the parsed response data.
The request options.
Response
The raw response from the request.
Promise<VetchResponse<T>>
- The parsed response.
protected prepareBody(request): undefined | string;Defined in: server-client/dist/lib/client.d.ts:158
Prepares the body for the request based on the content type.
The request options.
undefined | string
- The prepared request body as a string or undefined.
protected prepareRequest(request): Promise<VetchOptions>;Defined in: server-client/dist/lib/client.d.ts:151
Prepares the request with necessary headers, authentication, and query parameters.
The initial request options.
Promise<VetchOptions>
- The modified request options.
sendDeleteRequest<T>(url): Promise<VetchResponse<T>>;Defined in: server-client/dist/lib/client.d.ts:78
Sends a DELETE request to the specified URL.
T
string
The URL endpoint for the DELETE request.
Promise<VetchResponse<T>>
- The response from the DELETE request.
sendFormSubmitRequest<T>(url, payload?): Promise<VetchResponse<T>>;Defined in: server-client/dist/lib/client.d.ts:86
Sends a POST request with form data to the specified URL.
T
string
The URL endpoint for the POST request.
Record<string, undefined | string>
Optional payload containing form data to send with the POST request.
Promise<VetchResponse<T>>
- The response from the POST request.
sendGetRequest<T>(url, queryParams?): Promise<VetchResponse<T>>;Defined in: server-client/dist/lib/client.d.ts:94
Sends a GET request to the specified URL with optional query parameters.
T
string
The URL endpoint for the GET request.
Optional query parameters to append to the URL. These should be compatible with Node's URLSearchParams.
Promise<VetchResponse<T>>
- The response from the GET request.
sendPatchRequest<T>(url, payload?): Promise<VetchResponse<T>>;Defined in: server-client/dist/lib/client.d.ts:104
Sends a PATCH request to the specified URL with an optional payload.
T
string
The URL endpoint for the PATCH request.
Optional payload to be sent as the body of the PATCH request.
Promise<VetchResponse<T>>
- The response from the PATCH request.
sendPostRequest<T>(url, payload?): Promise<VetchResponse<T>>;Defined in: server-client/dist/lib/client.d.ts:114
Sends a POST request to the specified URL with an optional payload.
T
string
The URL endpoint for the POST request.
Optional payload to be sent as the body of the POST request.
Promise<VetchResponse<T>>
- The response from the POST request.
sendPutRequest<T>(url, payload?): Promise<VetchResponse<T>>;Defined in: server-client/dist/lib/client.d.ts:124
Sends a PUT request to the specified URL with an optional payload.
T
string
The URL endpoint for the PUT request.
Optional payload to be sent as the body of the PUT request.
Promise<VetchResponse<T>>
- The response from the PUT request.
sendRequest<T>(request): Promise<VetchResponse<T>>;Defined in: server-client/dist/lib/client.d.ts:144
Sends a request adding necessary headers, handling authentication, and parsing the response.
T
The options defining the request, including URL, method, headers, and data.
Promise<VetchResponse<T>>
- The parsed response from the request.
sendRequestWithData<T>(
method,
url,
payload?): Promise<VetchResponse<T>>;Defined in: server-client/dist/lib/client.d.ts:135
Sends a request with JSON-encoded data to the specified URL using the provided HTTP method.
T
The HTTP method to be used for the request (only POST, PATCH, or PUT are acceptable).
string
The URL endpoint for the request.
Optional payload to be sent as the body of the request, JSON-encoded.
Promise<VetchResponse<T>>
- The response from the request.
standardLookup(phoneNumber, options?): Promise<StandardResponse>;Defined in: number-insights/lib/number-insights.ts:175
Perform a standard number lookup operation.
string
The phone number to perform the lookup for.
Additional options for the lookup.
Promise<StandardResponse>
A promise that resolves to the standard lookup response.
const lookup = await numberInsightsClient.standardLookup(
'15555551212',
);
console.log(`The request ID is ${lookup.request_id}`);Lookup with the cname option:
const lookup = await numberInsightsClient.standardLookup(
'15555551212',
{ cname: true },
);
console.log(`The request ID is ${lookup.request_id}`);type AdvancedLookupOptions = StandardLookupOptions & object;Defined in: number-insights/lib/types/AdvancedLookupOptions.ts:6
Interface representing advanced lookup options for a phone number lookup operation.
optional real_time_data: boolean;Indicates whether real-time data should be included in the lookup.
If true, real-time data is included; otherwise, it's not included.
type AdvancedResponse = StandardResponse & object;Defined in: number-insights/lib/types/Responses/AdvancedResponse.ts:18
Type representing an advanced response from a phone number lookup operation.
lookup_outcome: LookupOutcome;The outcome of the lookup operation, represented by a LookupOutcome enum value.
lookup_outcome_message: string;A message describing the outcome of the lookup operation.
reachable: Reachable;The reachability status of the phone number, represented by a Reachable enum value.
real_time_data: RealTimeDataResponse;Real-time data related to the phone number.
roaming: RoamingDataResponse | string;Information about the roaming status of the phone number.
valid_number: ValidNumber;The validity status of the phone number, represented by a ValidNumber enum value.
Vonage API's will return information using snake_case. This represents the
pure response before the client will transform the keys into camelCase.
type AsyncAdvancedLookupOptions = StandardLookupOptions & object;Defined in: number-insights/lib/types/AsyncAdvancedLookupOptions.ts:6
Interface representing asynchronous advanced lookup options for a phone number lookup operation.
callback: string;The callback URL to which the lookup response will be sent asynchronously.
type AsyncAdvancedResponse = object;Defined in: number-insights/lib/types/Responses/AsyncAdvancedResponse.ts:9
Type representing an asynchronous advanced response from a phone number lookup operation. This response may include additional details about the request and its status.
Vonage API's will return information using snake_case. This represents the
pure response before the client will transform the keys into camelCase.
error_text: string;Defined in: number-insights/lib/types/Responses/AsyncAdvancedResponse.ts:38
Any error text or message associated with the response.
number: string;Defined in: number-insights/lib/types/Responses/AsyncAdvancedResponse.ts:18
The phone number associated with the response.
remaining_balance: string;Defined in: number-insights/lib/types/Responses/AsyncAdvancedResponse.ts:23
Your account balance in EUR after this request.
request_id: string;Defined in: number-insights/lib/types/Responses/AsyncAdvancedResponse.ts:13
The unique identifier for the request.
request_price: string;Defined in: number-insights/lib/types/Responses/AsyncAdvancedResponse.ts:28
The amount in EUR charged to your account for this request.
status: number;Defined in: number-insights/lib/types/Responses/AsyncAdvancedResponse.ts:33
The status code of the response.
type BasicLookupOptions = object;Defined in: number-insights/lib/types/BasicLookupOptions.ts:4
Basic lookup options for a phone number lookup operation.
optional country: string;Defined in: number-insights/lib/types/BasicLookupOptions.ts:8
The two-character country code for the phone number's country.
type BasicResponse = object;Defined in: number-insights/lib/types/Responses/BasicResponse.ts:8
Type representing a basic response from a phone number lookup operation.
Vonage API's will return information using snake_case. This represents the
pure response before the client will transform the keys into camelCase.
country_code: string;Defined in: number-insights/lib/types/Responses/BasicResponse.ts:37
The two-character country code for the phone number.
country_code_iso3: string;Defined in: number-insights/lib/types/Responses/BasicResponse.ts:42
The three-character country code for the phone number.
country_name: string;Defined in: number-insights/lib/types/Responses/BasicResponse.ts:47
The full name of the country that the phone number is registered in.
country_prefix: string;Defined in: number-insights/lib/types/Responses/BasicResponse.ts:52
The numeric prefix for the country that the phone number is registered in.
international_format_number: string;Defined in: number-insights/lib/types/Responses/BasicResponse.ts:27
The phone number in international format.
national_format_number: string;Defined in: number-insights/lib/types/Responses/BasicResponse.ts:32
The phone number in the format used by the country.
request_id: string;Defined in: number-insights/lib/types/Responses/BasicResponse.ts:22
The unique identifier for the request.
status: number;Defined in: number-insights/lib/types/Responses/BasicResponse.ts:12
The status code of the response.
status_message: string;Defined in: number-insights/lib/types/Responses/BasicResponse.ts:17
The status message of the response.
type CallerIdentityResponse = object;Defined in: number-insights/lib/types/Responses/CallerIdentityResponse.ts:10
Type representing the identity of a caller.
Vonage API's will return information using snake_case. This represents the
pure response before the client will transform the keys into camelCase.
caller_name: string;Defined in: number-insights/lib/types/Responses/CallerIdentityResponse.ts:15
The caller's name.
caller_type: CallerType;Defined in: number-insights/lib/types/Responses/CallerIdentityResponse.ts:12
The type of the caller, either "business," "consumer," or "unknown."
first_name: string;Defined in: number-insights/lib/types/Responses/CallerIdentityResponse.ts:18
The caller's first name.
last_name: string;Defined in: number-insights/lib/types/Responses/CallerIdentityResponse.ts:21
The caller's last name.
type CarrierInfoResponse = object;Defined in: number-insights/lib/types/Responses/CarrierInforResponse.ts:10
Type representing carrier information.
Vonage API's will return information using snake_case. This represents the
pure response before the client will transform the keys into camelCase.
country: string;Defined in: number-insights/lib/types/Responses/CarrierInforResponse.ts:18
The country in which the carrier operates.
name: string;Defined in: number-insights/lib/types/Responses/CarrierInforResponse.ts:15
The full name of the carrier.
network_code: string;Defined in: number-insights/lib/types/Responses/CarrierInforResponse.ts:12
The network code associated with the carrier.
network_type: NetworkType;Defined in: number-insights/lib/types/Responses/CarrierInforResponse.ts:21
The type of network associated with the carrier.
type NumberInsightsResponse<T> = VetchResponse<T>;Defined in: number-insights/lib/types/NumberInsightsResponse.ts:7
Interface representing a response from a number insights operation.
This extends the VetchResponse<T> interface.
T
type RealTimeDataResponse = object;Defined in: number-insights/lib/types/Responses/RealTimeDataResponse.ts:10
Type representing real-time data related to a phone number.
This service will be removed
Vonage API's will return information using snake_case. This represents the
pure response before the client will transform the keys into camelCase.
active_status: string;Defined in: number-insights/lib/types/Responses/RealTimeDataResponse.ts:11
handset_status: string;Defined in: number-insights/lib/types/Responses/RealTimeDataResponse.ts:12
type RoamingDataResponse = object;Defined in: number-insights/lib/types/Responses/RoamingDataResponse.ts:8
Type representing information about the roaming status of a phone number.
Vonage API's will return information using snake_case. This represents the
pure response before the client will transform the keys into camelCase.
roaming_country_code: string;Defined in: number-insights/lib/types/Responses/RoamingDataResponse.ts:10
roaming_network_code: string;Defined in: number-insights/lib/types/Responses/RoamingDataResponse.ts:11
roaming_network_name: string;Defined in: number-insights/lib/types/Responses/RoamingDataResponse.ts:12
status: string;Defined in: number-insights/lib/types/Responses/RoamingDataResponse.ts:9
type StandardLookupOptions = BasicLookupOptions & object;Defined in: number-insights/lib/types/StandardLookupOptions.ts:6
Interface representing standard lookup options for a phone number lookup operation.
optional cname: boolean;Indicates whether caller name (CNAME) information should be included in the lookup.
If true, CNAME information is included; otherwise, it's not included.
type StandardResponse = BasicResponse & object;Defined in: number-insights/lib/types/Responses/StandardResponse.ts:14
Type representing a standard response from a phone number lookup operation. This response includes various details such as pricing, carrier information, porting status, and caller identity.
caller_identity: CallerIdentityResponse;Information about the caller's identity.
caller_name: string;Full name of the person or business who owns the phone number.
caller_type: CallerType;The type of caller, either "business," "consumer," or "unknown."
country_code: string;The two-character country code for the phone number.
country_code_iso3: string;The three-character country code for the phone number.
country_name: string;The full name of the country that the phone number is registered in.
country_prefix: string;The numeric prefix for the country that the phone number is registered in.
current_carrier: CarrierInfoResponse;Information about the current carrier of the phone number.
first_name: string;First name of the person who owns the phone number.
international_format_number: string;The phone number in international format.
last_name: string;Last name of the person who owns the phone number.
national_format_number: string;The phone number in the format used by the country.
original_carrier: CarrierInfoResponse;Information about the original carrier of the phone number.
ported: string;Porting status of the phone number.
refund_price: string;The refund amount in EUR, reflecting lookup and CNAM pricing.
remaining_balance: string;Your account balance in EUR after this request.
request_id: string;The unique identifier for the request.
request_price: string;The price charged for the request in EUR.
status: number;The status code of the response.
status_message: string;The status message of the response.
Vonage API's will return information using snake_case. This represents the
pure response before the client will transform the keys into camelCase.