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

Safe List

(information)

Safe List API is in Pilot

This Verify feature is currently in the Pilot maturity stage.

Verify Customers who have enabled Fraud Guard will have default access to the Safe List API. Fraud Guard is now in the GA maturity stage and is available to all Verify customers at no extra cost.

If you are not using Fraud Guard, you'll need to contact sales(link takes you to an external page) to request access to this API.

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

Safe List API allows you to maintain a list of phone numbers that will never be blocked by Verify Fraud Guard or Geo permissions. While we are always adapting our fraud detection model to keep false positives extremely low, Safe List API adds another layer of protection by letting you mark 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 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

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

timeouts page anchor

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

Safe List Response Properties

safe-list-response-properties page anchor

These properties are returned in the JSON response output.

Property nameTypeRequiredDescriptionChild 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

add-a-phone-number page anchor

POST https://verify.twilio.com/v2/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.

Request body parameters

request-body-parameters page anchor
Encoding type:application/x-www-form-urlencoded
SchemaExample
Property nameTypeRequiredDescriptionChild 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 ListLink to code sample: Add a Phone Number to the Safe List
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 createSafelist() {

11
  const safelist = await client.verify.v2.safelist.create({

12
    phoneNumber: "+18001234567",

13
  });

14


15
  console.log(safelist.sid);

16
}

17


18
createSafelist();

Response

1
{

2
  "sid": "GNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "phone_number": "+18001234567",

4
  "url": "https://verify.twilio.com/v2/SafeList/Numbers/+18001234567"

5
}

Check a Phone Number

check-a-phone-number page anchor

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

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.

Path parameters

path-parameters page anchor
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 ListLink to code sample: Check if a Phone Number is in the Safe List
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 fetchSafelist() {

11
  const safelist = await client.verify.v2.safelist("+18001234567").fetch();

12


13
  console.log(safelist.sid);

14
}

15


16
fetchSafelist();

Response

1
{

2
  "sid": "GNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "phone_number": "+18001234567",

4
  "url": "https://verify.twilio.com/v2/SafeList/Numbers/+18001234567"

5
}

Remove a Phone Number

remove-a-phone-number page anchor

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

Removes a single phone number from 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.

Path parameters

path-parameters-1 page anchor
Property nameTypeRequiredPIIDescription
phoneNumberstring
required
Not PII

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

Remove a Phone Number from the Safe ListLink to code sample: Remove a Phone Number from the Safe List
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 deleteSafelist() {

11
  await client.verify.v2.safelist("+18001234567").remove();

12
}

13


14
deleteSafelist();