Deactivated Numbers API - Overview

The Deactivated Numbers API can be used to get reports with daily lists of deactivated phone numbers. These should be used to ensure you don't use Telesign products to send SMS messages to these numbers while they are deactivated.

🚧

CAUTION:

Be sure to use the Deactivated Numbers API with your Telesign SMS and/or SMS Verify API integration, so you don't send messages to deactivated phone numbers. This may be required to comply with government or carrier restrictions.

General requirements

• Base URL: deact-api.telesign.com
• Protocols: https
• Authentication: Basic (easiest to implement) or Digest
• Encoding: Accepts only UTF-8 unicode characters as inputs.
• Responds with: application/json or application/octet-stream

Basic usage

1. Create a chron job that makes a GET https://deact-api.telesign.com/files request once per day, to get the list of available files. Save the list to your system with an associated date of request.
2. Diff the list against your previous list. Create a new list of only the new filenames.
3. Iterate through the new filenames list, making a GET https://deact-api.telesign.com/download/{file_name} request to download each file.
4. In each response, save the body content to a file with the same name on your system. Note that this is raw ZIP file contents.
5. Uncompress each ZIP file, resulting in a .csv or other data file for each one.
6. Parse each data file.
7. (Verizon Wireless only) Purge the data in the report of all records that do not have the value deactivated in the status column. For other carriers, you can assume all records represent deactivated numbers. See Deactivated Numbers API - Report columns for more details on the columns in each report.
8. Save the records to one or more databases of do-not-send numbers. Use these databases with your Telesign messaging integrations to ensure you don't send messages when it is against regulations for deactivated numbers.
9. Remove records from the do-not-send databases as needed based on individual carriers' restrictions. A deactivated number is only in do-not-send status for a limited period of time, which varies by carrier. See Deactivated Numbers API - Details by carrier for those time ranges.

Documentation by category

• Reference
  • GET https://deact-api.telesign.com/files
  • GET https://deact-api.telesign.com/download/{file_name}
• Docs
  • Deactivated Numbers API - Report columns
  • Deactivated Numbers API - Details by carrier