Number Deactivation Subscription

PhoneID Number Deactivation Subscription Management enables you to obtain information about mobile phone numbers that have been deactivated. You submit a list of phone numbers in subscription files (up to one million phone numbers per file) to PhoneID Number Deactivation. TeleSign monitors the phone numbers’ deactivation dates, based on information from mobile carriers and other sources. On a daily basis, TeleSign creates a deactivation file which contains deactivation information on the phone numbers in your subscription list. TeleSign uploads the deactivation file to your dedicated folder. You can then download the deactivation file and use the data to handle deactivated mobile numbers appropriately.

Setting Up the Subscription Service

Contact TeleSign Client Services to enroll in the PhoneID Number Deactivation Subscription Management program. You must provide the following information in order to obtain access to TeleSign’s SFTP server:

  • IP address
  • Public SSH key

After you provide this information, TeleSign assigns you a user name, and provides you with connection details:

  • Username
  • SFTP server: sftp.telesign.com
  • Port number: 22

TeleSign creates folders for you on the SFTP server to allow you to access your Number Deactivation data. The folders have the following structure:

sftp.telesign.com
  <your-home-directory>
    inbound
      number_deactivation
    outbound
      number_deactivation
  • ~/inbound/number_deactivation: The folder to which you upload your subscription files containing the phone numbers that you want to subscribe/unsubscribe for monitoring by PID Number Deactivation.

  • ~/outbound/number_deactivation: The folder to which TeleSign posts the daily deactivation file (with deactivation timestamps) that matched your subscription files. It also contains subscription error output files created during the subscription file processing.

NOTE:

Files on the SFTP server will be deleted 7 days after the upload date. This includes all files: subscription files, deactivation files, and subscription error output files.

Inbound Subscription File

You can subscribe a batch of phone numbers to PhoneID Number Deactivation by creating a file that contains the phone numbers to be monitored. Upload the file you create to your ~/inbound/number_deactivation folder on the TeleSign SFTP server. The suggested file name is . You can send all the data in a single file. Your file names should be unique.

NOTE:

Each subscription file includes the unique creation date and time as part of the file name. A subscription file can contain a maximum of one million phone numbers. If you have more than one million phone numbers, submit additional subscription files, each one containing no more than one million phone numbers.

You must format the subscription file as described below.

To submit numbers to be subscribed or unsubscribed for PhoneID Number Deactivation, upload them in a subscription file (one million phone numbers maximum per file). You can use the file both for initial enrollment of phone numbers, and for subsequent additions to or deletions from the subscription list.

The subscription file must be submitted in a specific format, defined as follows:

  • The file must be tab-delimited ASCII text (TSV).

  • The file must be named with the following format: TELESIGN_YYYYMMDDHHMISS.in.tsv

    Where:

    • YYYYMMDDTHHMMSS specifies the creation date and time of the file in UTC, where T is a delimiter between date and time. The creation date and time should be unique if there are many files for uploading.

    Example: TELESIGN_20151230T160500.tsv

  • The contents of the file must contain a file header and one record per line (one record per row) as follows:

File Header Format

Field Sample Values Max Length
providerId Name of data provider TELESIGN 24
fileCreateTimestamp File create time in UTC 2018-01-05T05:48:45Z 24
total Total number of records excluding header 100275 10

Record Format

Field Description Sample Values Max Length
endClientId End Client Identifier (assigned by TeleSign) XYZ 24
clientCustId Cleint assigned Unique Id to each customer mobile 5634123XRFT 64
mdn Phone number with country code 15555551212 16
requestType Request Type ADD DELETE 16
  • The maximum number of records in each file is one million.

In order to keep the data consistent, each phone number should occur only once in each file. If there are multiple records containing the same phone number in the same file (that is, a non-unique record), the following rule will apply:

  • If the value of the ADD/DELETE indicator is the same in all of the non-unique records in a file, the specified action (subscribe or unsubscribe) is applied for that phone number. The invalid records will be listed in the subscription error output file.
  • If there are various values of the ADD/DELETE indicator in a non-unique record in a single file, all the records for that phone number will be ignored. These phone numbers will NOT be processed. The invalid records will be listed in the subscription error output file.
NOTE:

Submitted phone numbers all go through phone number cleansing, a process that corrects common formatting issues in submitted phone numbers.

Outbound Subscription File

A response file is generated for every inbound file and placed in /<>/Outbound folder. All fields in this file are TAB separated.You are expected to monitor this folder to download the response files. Response files are named the same as the inbound file but with .out.tsv extension (for ex: TELESIGN_YYYYMMDDHHMISS.out.tsv). If a file is rejected, the inbound file is renamed to .rej.tsv extension (Ex: TELESIGN_YYYYMMDDHHMISS.rej.tsv) and is copied to the Outbound folder.

The file contains a header line and one row for each record included.

Header Format

Field Description Sample Values Max Length
providerId Name of the data provider TELESIGN 24
fileCreateTimestamp File create time in UTC 2018-01-05T05:48:45Z 24
total total number of records processed 100275 10
successfulCount total number of records successful 100105 10
failedCount total number of records failed 170 10

Record Format

Field Description Sample Values Max Length
endClientId End Client Identifier (assigned by TeleSign) XYZ 24
clientCustId Client assigned unique id to each customer mobile 5634123XRFT 64
telesignCustId Unique id (assigned by TeleSign) 5C7603D0-A0D5-4E19-BFFF-160AE1F1C677 64
mdn Phone number with country code 15555551212 16
requestType Request Type ADD, DELETE 6
status Status of the request ADDED, DELETED, REJECTED, NOT_FOUND, ALREADY_ADDED, ALREADY_DELETED, DEACTIVATED, REACTIVATED 16
failedReason Failed Reason (valid for REJECTED) invalid mdn, mdn does not exist 128
monitoringStartDate number is monitored since - applicable to statuses ADDED, DELETED, ALREADY_ADDED, ALREADY_DELETED, REACTIVATED 2018-01-05T05:48:45Z 24
monitoringEndDate monitoring stopped date - applicable to statuses DELETED, ALREADY_DELETED 2018-01-05T05:48:45Z 24

Alerts - Consuming Number Deactivation Data

TeleSign monitors all your subscribed phone numbers to detect deactivated phone numbers, and reports on them in a daily alerts file. The latest alerts file only reports new information about deactivated phone numbers. If information about a deactivated phone number appeared in a previous report, it will not appear again unless the phone number is deactivated again. If a phone number is deactivated an additional time, it appears in the daily deactivation file with the latest deactivation timestamp. Possible statuses for a number are:

  • ported - if a number is identified as ported to a new carrier. Existing carrier details and new carrier details are returned in the alerts file.
  • deactivated - if a number is deactivated, the current carrier details are returned in the alerts file along with this status update.
  • swapped - if a number is swapped, the status is updated to swapped and the new phone number is provided in the “Swapped To” field. Carrier details will be added to the alerts file. If you want to monitor the new phone number, you must send the phone number as part of a subscription file with a request to ADD.
NOTE:

Files on the SFTP server will be deleted 7 days after the upload date.

TeleSign provides the alerts file in the following format:

  • The file is tab-delimited ASCII text (TSV).

  • The file is named in the following format: TELESIGN_YYYYMMDDHHMISS.alerts.tsv

    Where:

    • YYYYMMDDTHHMMSS specifies the creation date and time of the file in UTC, where T is a delimiter between date and time.

    Example: TELESIGN_20151230T160500.alerts.tsv

  • The file contains a file header and one record per row.

Header Format

Field Description Sample Values Max Length
providerId Name of data provider TELESIGN 24
fileCreateTimestamp File create time in UTC 2018-01-05T05:48:45Z 24
total Total number of records monitored 2500275 10
deactivatedCount Total number of records deactivated 4005 10
portedCount Total number of records ported 1170 10
swappedCount Total number of records swapped 2875 10

Record Format

Field Description Sample Value Max Length
endClientId End Client Identifier (assigned by TeleSign) XYZ 24
clientCustId Client assigned unique id to each customer mobile 5634123XRFT 64
telesignCustId Unique Id (assigned by TeleSign) 5C7603D0-A0D5-4E19-BFFF-160AE1F1C677 64
mdn Phone number with country code 15555551212 16
lineStatus status of phone line DEACTIVATED PORTED SWAPPED 16
carrierCountry country of carrier USA (3 char country code) 3
carrierName carrier name ATT 64
monitoringStartDate number is monitored since date 2018-01-05T05:48:45Z 24
deactivatedDate date the line was deactivated (YYYY-MM-DD) (applicable to DEACTIVATED numbers) 2018-01-05 10
swappedDate date line was swapped (YYYY-MM-DD) (applicable to SWAPPED numbers) 2018-01-05 10
swappedToNumber line was swapped to this number (applicable to SWAPPED numbers) 15555551212 16
monitoringEndDate monitoring end date (applicable to SWAPPED numbers) 2018-01-05T05:48:45Z 24
portedDate date line was ported (applicable to PORTED numbers) 2018-01-05T05:48:45Z 24
portedToCarrierCountry country of the ported carrier (applicable to PORTED numbers) USA (3 char country code) 3
portedToCarrierName ported carrier name (applicable to PORTED numbers) VZW 64