Menu

Expand
Rate this page:

Safe List

Safe List API is in Pilot!

This Verify feature is currently in the Pilot maturity stage, which means that you'll need to contact sales to request access to the API.

Note: Verify Customers who have enabled Fraud Guard will have default access to the Safe List API. Like Fraud Guard, 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

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 1 second.

Safe List Response Properties

These properties are returned in the JSON response output.

Resource Properties in REST API format
sid
sid<GN> Not PII

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

phone_number

The phone number in SafeList.

url
url 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 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
Parameters in REST API format
phone_number
Required
post string PII MTL: 0 DAYS

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

Example 1
        
        
        

        Check a Phone Number

        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.

        Parameters
        Parameters in REST API format
        phone_number
        Path
        get string PII MTL: 0 DAYS

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

        Example 1
              
              
              

              Remove a Phone Number

              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.

              Parameters
              Parameters in REST API format
              phone_number
              Path
              delete string PII MTL: 0 DAYS

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

              Example 1
                    
                    
                    
                    Rate this page:

                    Need some help?

                    We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

                          
                          
                          

                          Thank you for your feedback!

                          Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

                          Sending your feedback...
                          🎉 Thank you for your feedback!
                          Something went wrong. Please try again.

                          Thanks for your feedback!

                          thanks-feedback-gif