Skip to contentSkip to navigationSkip to topbar
Twilio Docs
Rate this page:
On this page

Global Safe List

(information)

Info

Global Safe List API is now in GA!

This feature is currently in the GA maturity stage.

Customers using the below products will now have access to the Global Safe List API.

  1. Verify customers who have enabled Fraud Guard
  2. Verify customers who have enabled Geo Permissions
  3. Programmable Messaging customers who have enabled SMS Pumping Protection and are seeing 30450 error codes
  4. Programmable Messaging customers who are seeing 30453 error codes

Note : Global Safe List API currently only supports the SMS channel.

Global Safe List API allows you to maintain a list of phone numbers that will never be blocked by Verify Fraud Guard, Verify Geo Permissions, Programmable Messaging SMS Pumping Protection or any other internal fraud & risk check solution.

While we are always adapting our fraud detection systems to keep false positives extremely low, Global Safe List API adds another layer of protection by letting you mark legitimate phone numbers as safe to ensure they are never erroneously blocked.

This API contains three endpoints:

  1. Add a Phone Number
  2. Check a Phone Number
  3. Remove a Phone Number

Alternatively, you can add a previously blocked phone number to the Global Safe List via Twilio Console on the Verify Logs Blocked Verifications tab(link takes you to an external page). See Viewing Logs With Twilio Console for more information.

Rate limits

rate-limits page anchor

Global Safe List API provides a built-in rate limit of 500 requests per minute. If you reach this limit, you will start receiving HTTP 429 "Too Many Requests" responses.

Timeouts

timeouts page anchor

Global Safe List API has a timeout value of 15 seconds. However, its 99th percentile is within 1 second.

Global Safe List Response Properties

global-safe-list-response-properties page anchor

These properties are returned in the JSON response output.

Resource properties
sidtype: SID<GN>Not PII

The unique string that we created to identify the SafeList resource.

phone_numbertype: stringPII MTL: 0 days

The phone number in SafeList.

Add a Phone Number

add-a-phone-number page anchor
POST https://accounts.twilio.com/v1/SafeList/Numbers

Adds a single phone number to the Safe List based on the given phone_number parameter. Phone numbers must be in E.164 format.

If attempting to add a number that already exists in the Safe List, HTTP 400 with Error Code 60411 will be returned. Phone numbers will remain in the Safe List indefinitely until they are explicitly removed.

Parameters

create-parameters page anchor
Request body parameters
PhoneNumbertype: stringPII MTL: 0 days
Required

The phone number to be added in SafeList. Phone numbers must be in E.164 format(link takes you to an external page).

Add a Phone Number to the Safe List

add-a-phone-number-to-the-safe-list page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.accounts.v1.safelist
_10
.create({phoneNumber: '+18001234567'})
_10
.then(safelist => console.log(safelist.sid));

Output

_10
{
_10
"sid": "GNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"phone_number": "+18001234567"
_10
}

Check a Phone Number

check-a-phone-number page anchor
GET https://accounts.twilio.com/v1/SafeList/Numbers

Checks if a single phone number is in the Safe List based on the given phone_number parameter. Phone numbers must be in E.164 format.

If the given phone number is not in the Safe List, HTTP 404 will be returned.

Parameters

fetch-parameters page anchor
URI parameters
PhoneNumbertype: stringPII MTL: 0 days
Query Parameter

The phone number to be fetched from SafeList. Phone numbers must be in E.164 format(link takes you to an external page).

Check if a Phone Number is in the Safe List

check-if-a-phone-number-is-in-the-safe-list page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.accounts.v1.safelist
_10
.fetch({phoneNumber: '+18001234567'})
_10
.then(safelist => console.log(safelist.sid));

Output

_10
{
_10
"sid": "GNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"phone_number": "+18001234567"
_10
}

Remove a Phone Number

remove-a-phone-number page anchor
DELETE https://accounts.twilio.com/v1/SafeList/Numbers

Removes a phone number from the Safe List. Phone number must be in E.164 format.

If the given phone number is not in the Safe List, HTTP 404 will be returned.

Parameters

delete-parameters page anchor
URI parameters
PhoneNumbertype: stringPII MTL: 0 days
Query Parameter

The phone number to be removed from SafeList. Phone numbers must be in E.164 format(link takes you to an external page).

Remove a Phone Number from the Safe List

remove-a-phone-number-from-the-safe-list page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.accounts.v1.safelist.remove({phoneNumber: '+18001234567'});

Rate this page: