Version 2 of the Vonage Number Insight API Is Now in Beta!
Published on July 18, 2023

We're excited to announce that Version 2 of the Number Insight API is now in beta! Number Insight (NI) v2 is a powerful fraud prevention API with fraud-fighting tools to keep you and your users safe.

Fraud has long been a challenge for organizations and individuals alike. In 2021, the Communications Fraud Control Association found that fraud caused over $39 billion in global losses.

In recent years, 2-factor authentication (2FA) has become more prevalent to prevent bad actors from gaining access to real people's accounts and to prevent the creation of fake accounts on a platform. Those bad actors have developed methods to bypass 2FA checks in light of this. New forms of committing old crimes are also possible by abusing 2FA, such as using verification codes to commit toll fraud.

The Number Insight v2 API offers two key features to help protect you from fraudulent activities: Fraud Scoring and SIM Swap Detection. We're currently adding SDK support in Node.js, and we'll be adding v2 features to the other server SDKs we support too.

How Does Number Insight v2 Differ From Number Insight v1?

Version 2 of the Number Insight API provides methods to detect fraudulent behavior associated with a phone number. This contains some insight into the phone number, but v2 focuses on fraud-checking behavior.

For more detailed information about a phone number, look at Version 1 of the Number Insight API. Version 1 provides detailed phone number information that can be used to determine the validity and reachability of a phone number, among other properties.

How Does Number Insight v2 Work?

Number Insight v2 currently offers two functions: a fraud score calculation and a SIM swap check. They can be used together or separately to root out fraudulent activity. I'll explain both now.

Fraud Score: Identifying High-Risk Numbers

The Fraud Score tool evaluates phone data and user activity using artificial intelligence. By analyzing a combination of static and dynamic data such as phone type, telecom carrier, account ID, device ID, usage velocity, and behavioral patterns, a call to the Number Insight v2 API calculates and returns a fraud score, risk label, and recommended action to take. These metrics indicate the likelihood of fraudulent behavior associated with a specific phone number.

To integrate Fraud Score into your application, use the NI v2 API endpoint. Here's an example of how you can perform a fraud score lookup with curl:

curl "https://api.nexmo.com/v2/ni" \ -u "$VONAGE_API_KEY:$VONAGE_API_SECRET"\ -H 'Content-Type: application/json' \ -d '{ "type": "phone", "phone": "'$INSIGHT_NUMBER'", "insights": [ "fraud_score" ] }'

Using this method with a phone number used by somebody attempting fraud (this is the actual response for a real fraudulent number, which I've changed to protect our readers) returns JSON that looks like this:

{
    "request_id": "ccece533-ba5e-4a01-a735-c38e223e8c4d",
    "type": "phone",
    "phone": {
        "phone": "111111111111",
        "carrier": "Multiple Providers",
        "type": "RESTRICTED_PREMIUM"
    },
    "fraud_score": {
        "risk_score": "90",
        "risk_recommendation": "block",
        "label": "high",
        "status": "completed"
    },
}

Here, the risk_score is very high, at 90/100. The number is labeled as high risk, and the risk_recommendation given is to block this number. We can also see that the phone type is RESTRICTED_PREMIUM, which could indicate that it's used for toll fraud.

By incorporating Fraud Score into your account sign-up or registration process, you can preemptively identify potential red flags associated with phone numbers before onboarding clients. This proactive approach ensures a safer environment for your organization and your users.

SIM Swap Detection

SIM card swapping is a form of fraud that's popular with criminals trying to access user accounts that have 2FA enabled.

In a SIM card swap attack, a bad actor tricks a mobile network operator into transferring a victim's phone number to a new SIM card they control using information they've socially engineered from a victim. They can then intercept calls and messages, including 2FA messages, leading to unauthorized account access and identity theft.

The SIM Swap Detection feature of the Number Insight v2 API detects whether the SIM card associated with a phone number has been swapped within the past seven days. This provides additional protection against account takeover attempts, protecting your users.

You can use SIM Swap Detection by calling the NI v2 API. Here's a curl example:

curl "https://api.nexmo.com/v2/ni" \ -u "$VONAGE_API_KEY:$VONAGE_API_SECRET"\ -H 'Content-Type: application/json' \ -d '{ "type": "phone", "phone": "'$INSIGHT_NUMBER'", "insights": [ "sim_swap" ] }'

When this is called with a number you want to check for SIM swap fraud, you'll get an output like this:

{
    "request_id": "db5282b6-8046-4217-9c0e-d9c55d8696e9",
    "type": "phone",
    "phone": {
        "phone": "447777000777"
    },
    "sim_swap": {
        "status": "completed",
        "swapped": false
    }
}

The swapped status above is a boolean referring to whether the SIM card was swapped in the last seven days, where false here means no swap was detected - the SIM card was likely not swapped. Using the SIM swap feature is a quick way to verify if the 2FA number a customer is using is genuine. So, with minimal implementation effort, you can detect SIM card swap incidents and safeguard your users.

Guidelines and Notes

Using the Fraud Score and SIM swap features in the same API call is possible. You can do this by passing both items in a list to the insights object when the request is made, like this:

"insights": ["fraud_score", "sim_swap"]

There are also a couple of things to note when using the Fraud Score endpoint:

Fraud Score Context: the primary use case of the Fraud Score endpoint is to catch fraudulent numbers during account sign-ups.

  • For example, checking the phone number score during sign-in attempts may result in a degrading risk score if a user attempts to log in several times within a short period. The algorithm views this as an attempt to create several accounts using the same number.

Country-Specific Performance: The accuracy of the fraud score varies depending on the issuing country.

  • For example, Brazil, China, India, the UK, and the USA are among the countries with higher levels of accuracy.

Conclusion

The Number Insight v2 API is now in Beta. We'll shortly add Node.js SDK support and code samples. As we leave the beta phase, we'll add support and code samples for our PHP, Python, C#, Java, and Ruby SDKs. If you have questions, you can head to our Community Slack. We always love hearing about what you build with our APIs!

Max KahanPython Developer Advocate

Max is a Python Developer Advocate and Software Engineer who's interested in communications APIs, machine learning, developer experience and dance! His training is in Physics, but now he works on open-source projects and makes stuff to make developers' lives better.

Ready to start building?

Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls-all at your fingertips.

Subscribe to Our Developer Newsletter

Subscribe to our monthly newsletter to receive our latest updates on tutorials, releases, and events. No spam.