How to determine if a phone number still belongs to someone with the Twilio Lookup API

How to determine if a phone number still belongs to someone with the Twilio Lookup API

To stay compliant with the Telephone Consumer Protection Act (TCPA), you need to have consent to contact people from your application. One common challenge that can result in TCPA violations happens if a phone number that used to belong to someone who provided consent has been reassigned. You may have gotten consent for the phone number, but since it no longer is attached to the same individual you don't have consent to contact its new owner.

Twilio's Lookup API provides a deterministic way to check if a phone number was reassigned to help you improve contact rates, increase campaign efficiency, and avoid compliance fines. This feature is especially useful for marketing notifications.

How to set up and use the Twilio Lookup API for reassigned numbers

Prerequisites to using the Lookup API include:

1. A Twilio account - sign up today.
2. Twilio test credentials - find them in the Auth Tokens page of Console.
3. For production use, you will need additional approval to use the Reassigned Number data package. Approvals generally take 2-4 business days. Note - you will be able to use the API immediately in development with test credentials.

For this tutorial, you will call the Lookup API with test credentials to have a deterministic response representing reassigned numbers.

In addition to the phone number, the API request requires two parameters:

1. Fields: reassigned_number. The Lookup API has many data packages which are specified by the Fields parameter. See others.
2. LastVerifiedDate. Formatted as YYYYMMDD, this is the date you either acquired consent to contact the end user, last contacted the end user, or the end user last updated their phone number in your application.

Once you have your test credentials in hand. Use them to replace the credentials in the following request. Check out the documentation for how to make the same request using Node.js, Python, and more languages.

This returns a reassigned number in the response. You will see multiple other keys in the response that may be null like sim_swap or line_type_intelligence. This is because you can request multiple data packages with the Fields parameter. Lookup will also return formatting and validation information by default.

Note that the is_number_reassigned field is not a boolean response, but can be one of three options:

1. yes. The phone number has been reassigned since the last verified date and you should find another way to contact the user to re-request their phone number and consent to contact.
2. no. The phone number still belongs to the end user. This response indicates a safe harbor from TCPA violations with proof of consent.
3. no_data_available. Generally means your LastVerifiedDate is before January 2021 and that you should re-request consent to contact.

For additional responses, try other Magic Numbers for testing Lookup.

How does Twilio ensure the accuracy of the FCC database updates used for this feature?

Twilio uses the official database maintained by the Federal Communications Commission (FCC). This database updates monthly on the 16th day of each month. For customers who need to validate number reassignment status more than once per month, we suggest they refresh their database starting on the 17th of each month. Data obtained on the 17th of the month will remain valid until the database refreshes again on the 16th of the following month. If for any reason there is an issue with the database, the FCC has indicated the caller may be protected from liability with the proper documentation.

Debugging common error codes

When the API encounters an error, you will see the error code nested inside the reassigned_number response key. The response will still contain a 200 status code because you can request multiple Lookup packages in a given request and some of them may be successful.

There are four common errors you may encounter:

• 60606 - Package is not enabled. Request access using this form and test with Test Credentials and magic numbers in the meantime.
• 60607 - Request for a phone number outside the US. Reassigned numbers only support the US.
• 60617 - Missing LastVerifiedDate.
• 60618 - LastVerifiedDate is not correctly formatted. The correct format is YYYYMMDD. Remove all dashes or spaces.

Taking reassigned number detection into production

Compliance for marketing messages is essential and detecting reassigned numbers will help you avoid fines. Note that Twilio does not maintain a do not call list, so we encourage you to use Lookup Reassigned Numbers with the National Do Not Call List to determine consent to contact for your user base. Once you're ready to run your application in production, ensure you have carrier approval and start making requests with your production API keys instead of your test credentials.

Once you're set up to detect reassigned numbers, try out other Lookup data packages with the Code Exchange including detecting VoIP numbers with Line Type Intelligence or finding a SIM swapped phone number before sending an SMS 2FA request. Then you can integrate the Verify API to prove phone number possession and complete the user verification journey. I can't wait to see what you build and secure!