Getting the Fraud Score

(To be sunset on February 3rd, 2025)

The Fraud Score shows how likely a phone number is to be a fraudulent one. The score is provided on a scale of 0 to 100, with a higher score being the most likely.

Before you get started, sign up for a Vonage API account, if you haven't already.

Finding the score

curl -X 'POST' \ 'https://api.nexmo.com/v2/ni' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: Basic <token>' \ -d '{ "type": "phone", "phone": "447009000000", "insights": [ "fraud_score" ]}'

Be sure to replace the placeholder <token> in the snippet above with your Base64 encoded API key and secret, joined with a colon.

The Fraud Score check is a POST request with the insight type passed in as the request body.

You may check for the Fraud Score as shown above or request SIM Swap Detection by specifying the sim_swap keyword in the insights request body array.

Do note that you can also check both the Fraud Score and detect the SIM Swap status all in one request by passing both insight keywords into the request body i.e: sim_swap and fraud_score. See the API reference to learn more.

Response interpretation

The ${api_key} and ${api_secret} placeholders should be replaced with your API Key and Secret from your Vonage account.

Risk Score: This is a numerical score showing how risky a phone number is. It's based on a scale of 0 to 100, where 100 means the highest risk.
Risk Recommendation: This is a one-word summary of the risk_score. It can be one of the following:
- allow: Risk score: 0-45
- flag: Risk score: 46-60
- block: Risk score 61-100
Label: This is a more direct version of risk_recommendation. Its value can be one of the following: low, medium and high.
Status: This shows the current state of the request, with complete specifying the completion of the request.

Reference

Visit the API Reference to get a detailed understanding of the request above.

Notes

Here are a few things to note when using the Fraud Score endpoint:

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/login may result in a degrading risk score if a user attempts to log in several times within a short period. This is because the algorithm views this as an attempt to create several accounts using the same number.
The accuracy of the score varies depending on the issuing country. For example, Brazil, China, India, the United Kingdom, and the United States are among the countries with higher levels of accuracy.

What next?

You can also perform SIM Swap Detection. This reports if the phone number in question was recently issued to an existing account by the carrier.