Safe List

(information)

Pilot feature

This Verify feature is available as Pilot.

Verify customers who have turned on Fraud Guard can access the Safe List API. Fraud Guard is GA and all Verify customers can use it at no extra cost.

If you don't use Fraud Guard and want to use this API, contact sales.

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

Safe List API allows you to maintain a list of phone numbers that neither Verify Fraud Guard nor Geo permissions block. While Twilio adapts its fraud detection model to minimize false positives, Safe List API lets you mark phone numbers as safe so they never get blocked.

This API contains three endpoints:

Using Verify Logs Blocked Verifications in the Twilio Console, you can add a previously blocked phone number to the Safe List. To learn more about this feature, see Viewing Logs With Twilio Console.

Rate limits

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

Timeouts

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

Safe List Response Properties

The JSON response output returns these properties.

(information)

Identifier capitalization conventions

The capitalization of the multiple-word identifiers in the parameter and property lists changes to match the selected language's conventions.

Property nameTypeRequiredPIIDescriptionChild properties

sidSID<GN>

Optional

Not PII

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

Pattern: ^GN[0-9a-fA-F]{32}$Min length: 34Max length: 34

phoneNumberstring

Optional

PII MTL: 0 days

The phone number in SafeList.

urlstring<uri>

Optional

Not PII

The absolute URL of the SafeList resource.

Add a Phone Number

POST https://verify.twilio.com/v2/SafeList/Numbers

Adds a single phone number to the Safe List based on the provided phone_number parameter. Provide phone numbers in E.164 format.

If you attempt to add a number that exists in the Safe List, the API returns a HTTP 400 status with Error Code 60411. Phone numbers remain in the Safe List until explicitly removed.

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

phoneNumberstring

required

PII MTL: 0 days

The phone number to be added in SafeList. Phone numbers must be in E.164 format.

Add a Phone Number to the Safe List

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createSafelist() {
11  const safelist = await client.verify.v2.safelist.create({
12    phoneNumber: "+18001234567",
13  });
14
15  console.log(safelist.sid);
16}
17
18createSafelist();

Response

1{
2  "sid": "GNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "phone_number": "+18001234567",
4  "url": "https://verify.twilio.com/v2/SafeList/Numbers/+18001234567"
5}

Check a Phone Number

GET https://verify.twilio.com/v2/SafeList/Numbers/{PhoneNumber}

Checks if the provided phone_number parameter value exists in the Safe List. Provide phone numbers in E.164 format.

If the provided phone number isn't in the Safe List, the API returns a HTTP 404 status.

Path parameters

Property nameTypeRequiredPIIDescription

phoneNumberstring

required

PII MTL: 0 days

The phone number to be fetched from SafeList. Phone numbers must be in E.164 format.

Check if a Phone Number is in the Safe List

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchSafelist() {
11  const safelist = await client.verify.v2.safelist("+18001234567").fetch();
12
13  console.log(safelist.sid);
14}
15
16fetchSafelist();

Response

1{
2  "sid": "GNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "phone_number": "+18001234567",
4  "url": "https://verify.twilio.com/v2/SafeList/Numbers/+18001234567"
5}

Remove a Phone Number

DELETE https://verify.twilio.com/v2/SafeList/Numbers/{PhoneNumber}

Removes the provided phone_number parameter value exists in the Safe List. Provide phone numbers in E.164 format.

If the provided phone number isn't in the Safe List, the API returns a HTTP 404 status.

Path parameters

Property nameTypeRequiredPIIDescription

phoneNumberstring

required

PII MTL: 0 days

The phone number to be removed from SafeList. Phone numbers must be in E.164 format.

Remove a Phone Number from the Safe List

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function deleteSafelist() {
11  await client.verify.v2.safelist("+18001234567").remove();
12}
13
14deleteSafelist();