Deactivated Numbers API

The Deactivated Numbers API can be used to get reports with daily lists of deactivated numbers. These should be used to ensure you don’t send SMS messages to these numbers using our SMS and SMS Verify products while they remain deactivated.

CAUTION:

Add this API to your SMS and/or SMS Verify 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: rest-ww.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 /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 /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 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 Details by Operator for those time ranges.

Documentation by Category