SMS Pumping Risk Score

SMS Pumping Risk Score is available for phone numbers worldwide.

Note: Canadian phone numbers don't return carrier information. Twilio doesn't recommend using SMS Pumping Risk Score for US or Canadian phone numbers, as these regions are generally not targeted by SMS pumping fraud.

Make a GET /v2/PhoneNumbers/{PhoneNumber} request with the Fields=sms_pumping_risk query parameter.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function fetchPhoneNumber() {
11
  const phoneNumber = await client.lookups.v2
12
    .phoneNumbers("+447772000001")
13
    .fetch({ fields: "sms_pumping_risk" });
14

15
  console.log(phoneNumber.smsPumpingRisk);
16
}
17

18
fetchPhoneNumber();

1
{
2
  "calling_country_code": "1",
3
  "country_code": "US",
4
  "phone_number": "+447772000001",
5
  "national_format": "(415) 992-9960",
6
  "valid": true,
7
  "validation_errors": [],
8
  "caller_name": null,
9
  "sim_swap": null,
10
  "call_forwarding": null,
11
  "line_status": null,
12
  "line_type_intelligence": null,
13
  "identity_match": null,
14
  "reassigned_number": null,
15
  "sms_pumping_risk": {
16
    "carrier_risk_category": "moderate",
17
    "number_blocked": false,
18
    "number_blocked_date": null,
19
    "number_blocked_last_3_months": null,
20
    "sms_pumping_risk_score": 61,
21
    "error_code": null
22
  },
23
  "phone_number_quality_score": null,
24
  "pre_fill": null,
25
  "url": "https://lookups.twilio.com/v2/PhoneNumbers/+14159929960"
26
}

Optionally, you can include the PartnerSubId parameter to provide context for your sub-accounts, tenant IDs, sender IDs, or other segmentation. This additional context can improve the accuracy of the analysis.

1
curl -X GET "https://lookups.twilio.com/v2/PhoneNumbers/%2B447772000001?Fields=sms_pumping_risk&PartnerSubId=48006580138aee4528765f46923f58927ab72c94ddea0cdfc0235220792bcc8b" \
2
  -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

A SMS Pumping Risk Score request returns the following properties.

Note: Adding the PartnerSubId parameter in your request doesn't change the structure of the response.

Implementing SMS Pumping Risk Score depends on your application's structure and risk tolerance.

Use the SmsPumpingRiskScore property to decide whether to send a message, such as an OTP or other user-requested communication, based on the assessed risk level.

You can use the following general guidelines to assess the risk level of a phone number:

To include blocks currently applied to other customer accounts by Verify Fraud Guard, you can use the NumberBlocked property. This will block any messages where the property returns true. However, this might lead to higher false positive rates, particularly in high-risk countries.

You can also use other response properties to define custom conditions that trigger specific workflows in your system, aligned with your risk tolerance levels.

Twilio evaluates several risk signals associated with the phone number requested through the API and feeds those signals into its proprietary algorithm. The algorithm also considers your API request as a signal indicating a message request. To ensure accuracy, it's important for the algorithm to be able to see all traffic related to user-generated OTP requests in given countries.

Twilio considers the API request to Lookup as a signal so that customers—even those who don't use Twilio as their CPaaS provider for all traffic—can use a single product for SMS pumping fraud detection.

The risk score is specific to your Account SID. Keep in mind:

• No other customer's traffic impacts your risk scores.
• If you make API requests from multiple Account SID, the risk score for each Account SID will remain independent of one another.

Twilio recommends querying the Lookup API in shadow mode on your production traffic.

Alternatively, you can analyze traffic for a specific country over a certain period of time by querying the API in real-time. When you use this approach, it's important to consider the timing of message requests. For example, if you take 30 days of traffic for a specific country and feed that through the API in three minutes, the algorithm will assume all that traffic occurred within that three-minute window. This can significantly inflate the scores, leading to results that don't accurately reflect what they would be on your production traffic.

Yes. To make sure the solution is effective, you should make an API request for SMS Pumping Risk Score prior to every user-generated OTP request for a given country.

Twilio doesn't recommend caching the risk scores. The scores can change in seconds, depending on the traffic the API is seeing on your account. Caching scores can negatively impact the efficacy of this product:

• If a false positive occurs, caching will store that incorrect score. A phone number flagged as high risk one day during a fraud event can be a low risk tomorrow if the fraudster stops their activity.
• Caching scores prevents additional API requests for the same number. Fraudsters typically recycle phone numbers, but if the fraudster starts slowly ramping up traffic, the algorithm might not be able to detect the traffic pattern right away. By caching scores, you might allow thousands of phone numbers to continue receiving messages without being flagged as high risk. This can reduce the precision of the algorithm.

• Recommended: All countries outside the US and Canada. This includes smaller regions, such as the Caribbean islands that use the +1 country code, as these areas are more frequently targeted by SMS pumping fraud.
• Not Recommended: There is generally no need to use SMS Pumping Risk Score for US and Canadian phone numbers. These regions aren't common targets for SMS pumping fraud due to the lack of incentives for this type of activity. The algorithm isn't designed for US or Canadian traffic and its effectiveness in these regions might be limited.