Vonage Number Insights V2
Documentation / Vonage Number Insights V2
This is the Vonage Number Insight V2 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.
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 Number insights V2 API.
npm install @vonage/number-insight-v2yarn add @vonage/number-insight-v2Unlike the other SDK's this package is not include in the Vonage Server SDK for Node.js
const { Auth } = require('@vonage/auth');
const { NumberInsightV2 } = require('@vonage/number-insight-v2');
const credentials = new Auth({
apiKey: API_KEY,
apiSecret: API_SECRET
});
const options = {};
const niClient = new NumberInsightV2(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.numberInsightV2.basicLookup(PHONE_NUMBER)
vonage.numberInsightV2.checkForFraud({
type: 'phone',
phone: PHONE_NUMBER,
insights: [Insight.SIM_SWAP, Insight.FRAUD_SCORE],
})
.then(resp => console.log(resp))
.catch(err => console.error(err));Run:
npm run testDefined in: number-insight-v2/lib/enums/insight.ts:4
Enum representing the types of insights available for phone number checks.
| Enumeration Member | Value | Description | Defined in |
|---|---|---|---|
FRAUD_SCORE
|
"fraud_score" |
Use this insight to check the fraud score associated with a phone number. | number-insight-v2/lib/enums/insight.ts:8 |
SIM_SWAP
|
"sim_swap" |
Use this insight to check if a SIM swap has occurred for a phone number in the last 7 days. | number-insight-v2/lib/enums/insight.ts:13 |
Defined in: number-insight-v2/lib/enums/label.ts:4
Enum representing the labels for risk scores.
| Enumeration Member | Value | Description | Defined in |
|---|---|---|---|
HIGH
|
"high" |
Represents a high risk score. | number-insight-v2/lib/enums/label.ts:18 |
LOW
|
"low" |
Represents a low risk score. | number-insight-v2/lib/enums/label.ts:8 |
MEDIUM
|
"medium" |
Represents a medium risk score. | number-insight-v2/lib/enums/label.ts:13 |
Defined in: number-insight-v2/lib/enums/riskRecommendation.ts:4
Enum representing the recommendations based on risk scores.
| Enumeration Member | Value | Description | Defined in |
|---|---|---|---|
ALLOW
|
"allow" |
Indicates that it is recommended to allow the action based on the risk score. | number-insight-v2/lib/enums/riskRecommendation.ts:8 |
BLOCK
|
"block" |
Indicates that it is recommended to block the action based on the risk score. | number-insight-v2/lib/enums/riskRecommendation.ts:18 |
FLAG
|
"flag" |
Indicates that it is recommended to flag the action based on the risk score. | number-insight-v2/lib/enums/riskRecommendation.ts:13 |
Defined in: number-insight-v2/lib/enums/status.ts:4
Enum representing the possible status values for an operation.
| Enumeration Member | Value | Description | Defined in |
|---|---|---|---|
COMPLETED
|
"completed" |
Indicates that the operation has been completed successfully. | number-insight-v2/lib/enums/status.ts:8 |
FAILED
|
"failed" |
Indicates that the operation has failed. | number-insight-v2/lib/enums/status.ts:13 |
Defined in: number-insight-v2/lib/numberInsightV2.ts:8
Number Insight v2 is designed to give fraud scores for Application Integrations. This class represents the client for making fraud check requests.
new NumberInsightV2(credentials, options?): NumberInsightV2;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-insight-v2/lib/numberInsightV2.ts:9
The type of authentication used for the client's requests.
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
checkForFraud(params): Promise<FraudCheck>;Defined in: number-insight-v2/lib/numberInsightV2.ts:61
Make a fraud check request with the provided parameters.
The parameters for the fraud check request.
Promise<FraudCheck>
- A Promise that resolves with the fraud score response.
This service is deprecated and will be turned off.
Check for fraud on a phone number.
import { Insight } from '@vonage/number-insight-v2';
const score = await client.numberInsightV2.checkForFraud({
type: 'phone',
number: '447700900000',
insights: [
Insight.FRAUD_SCORE,
],
});
console.log(`Fraud score: ${score.riskScore}`);Check for SIM swap on a phone number.
import { Insight } from '@vonage/number-insight-v2';
const score = await client.numberInsightV2.checkForFraud({
type: 'phone',
number: '447700900000',
insights: [
Insight.SIM_SWAP,
],
});
console.log(`SIM swap detected: ${score.simSwap ? 'Yes' : 'No'}`);Check both fraud score and SIM swap on a phone number.
import { Insight } from '@vonage/number-insight-v2';
const score = await client.numberInsightV2.checkForFraud({
type: 'phone',
number: '447700900000',
insights: [
Insight.SIM_SWAP,
Insight.FRAUD_SCORE,
],
});
console.log(`SIM swap detected: ${score.simSwap ? 'Yes' : 'No'}`);
console.log(`Fraud score: ${score.riskScore}`);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.
type FraudCheck = object;Defined in: number-insight-v2/lib/types/fraudCheck.ts:10
Represents the result of a fraud check request.
This service is deprecated and will be turned off.
optional fraudScore: FraudScore;Defined in: number-insight-v2/lib/types/fraudCheck.ts:29
The result of the 'fraud_score' insight operation (optional).
phone: PhoneInfo;Defined in: number-insight-v2/lib/types/fraudCheck.ts:24
An object containing information about the phone number used in the fraud check operation(s).
requestId: string;Defined in: number-insight-v2/lib/types/fraudCheck.ts:14
Unique UUID for this request for reference.
optional simSwap: SimSwap;Defined in: number-insight-v2/lib/types/fraudCheck.ts:34
The result of the 'sim_swap' insight operation (optional).
type: "phone";Defined in: number-insight-v2/lib/types/fraudCheck.ts:19
The type of lookup used in the request. Currently always 'phone'.
type FraudCheckParameters = object;Defined in: number-insight-v2/lib/types/parameters/fraudParameters.ts:8
Represents the parameters for making a fraud check request.
This service is deprecated and will be turned off.
insights: Insight[];Defined in: number-insight-v2/lib/types/parameters/fraudParameters.ts:23
The insight(s) you need, at least one of: 'fraud_score' and 'sim_swap'.
phone: string;Defined in: number-insight-v2/lib/types/parameters/fraudParameters.ts:18
A single phone number that you need insight about in the E.164 format. Don't use a leading + or 00 when entering a phone number, start with the country code, e.g., 447700900000.
type: "phone";Defined in: number-insight-v2/lib/types/parameters/fraudParameters.ts:12
The type of lookup used in the request. Currently always 'phone'.
type FraudCheckRequest = object;Defined in: number-insight-v2/lib/types/requests/fraudCheckRequest.ts:10
Represents a fraud check request.
Vonage API's will return information using snake_case. This represents the
pure response before the client will transform the keys into camelCase.
insights: Insight[];Defined in: number-insight-v2/lib/types/requests/fraudCheckRequest.ts:25
The insight(s) you need, at least one of: 'fraud_score' and 'sim_swap'.
phone: string;Defined in: number-insight-v2/lib/types/requests/fraudCheckRequest.ts:20
A single phone number that you need insight about in the E.164 format. Don't use a leading + or 00 when entering a phone number, start with the country code, e.g., 447700900000.
type: "phone";Defined in: number-insight-v2/lib/types/requests/fraudCheckRequest.ts:14
The type of lookup used in the request. Currently always 'phone'.
type FraudCheckResponse = object & Omit<FraudCheck, "requestId" | "fraudScore" | "simSwap">;Defined in: number-insight-v2/lib/types/responses/fraudCheckResponse.ts:12
Represents the response from a fraud check request.
fraud_score: FraudScoreResponse;The response data for the 'fraud_score' insight operation.
request_id: string;Unique UUID for this request for reference.
sim_swap: SimSwap;The response data for the 'sim_swap' insight operation.
Vonage API's will return information using snake_case. This represents the
pure response before the client will transform the keys into camelCase.
type FraudScore = object;Defined in: number-insight-v2/lib/types/fraudScore.ts:8
Represents the result of the fraud_score insight operation.
This service is deprecated and will be turned off.
label: Label;Defined in: number-insight-v2/lib/types/fraudScore.ts:24
Mapping of risk score to a verbose description. Must be one of the values from the 'Label' enum.
riskRecommendation: RiskRecommendation;Defined in: number-insight-v2/lib/types/fraudScore.ts:18
Recommended action based on the riskScore. Must be one of the values from the 'RiskRecommendation' enum.
riskScore: string;Defined in: number-insight-v2/lib/types/fraudScore.ts:12
Score derived from evaluating fraud-related data associated with the phone number.
status: Status;Defined in: number-insight-v2/lib/types/fraudScore.ts:30
The status of the fraud_score call. Must be one of the values from the 'Status' enum.
type FraudScoreResponse = object & Omit<FraudScore, "riskRecommendation" | "riskScore">;Defined in: number-insight-v2/lib/types/responses/fraudScoreResponse.ts:11
Represents the response data for the 'fraud_score' insight operation.
risk_recommendation: RiskRecommendation;Recommended action based on the risk_score. Must be one of the values from the 'RiskRecommendation' enum.
risk_score: string;Score derived from evaluating fraud-related data associated with the 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.
type PhoneInfo = object;Defined in: number-insight-v2/lib/types/phoneInfo.ts:4
Represents information about a phone number.
optional carrier: string;Defined in: number-insight-v2/lib/types/phoneInfo.ts:14
The name of the network carrier (optional). Included if insights included 'fraud_score'.
phone: string;Defined in: number-insight-v2/lib/types/phoneInfo.ts:8
The phone number.
optional type: string;Defined in: number-insight-v2/lib/types/phoneInfo.ts:20
Type of phone (optional). Examples include Mobile, Landline, VOIP, PrePaid, Personal, Toll-Free. Included if insights included 'fraud_score'.
type SimSwap = object;Defined in: number-insight-v2/lib/types/simSwap.ts:6
Represents the result of the sim_swap insight operation.
optional reason: string;Defined in: number-insight-v2/lib/types/simSwap.ts:21
The reason for a sim swap error response. Returned only if the sim swap check fails.
status: Status;Defined in: number-insight-v2/lib/types/simSwap.ts:10
The status of the sim_swap call. Must be one of the values from the 'Status' enum.
optional swapped: boolean;Defined in: number-insight-v2/lib/types/simSwap.ts:16
true if the sim was swapped in the last 7 days, false otherwise. Returned only if the sim swap check succeeds.