Authentication
Try the API Explorer
APIs
SMS API
SMS Verify API
Bulk SMS API
Anonymous SMS API
Voice Verify API
Phone Numbers API
Score API
Get Status API
Completion API

Get Started with Add-ons

The PhoneID API is a REST API that provides a cleansed phone number, phone type, and telecom carrier information that can be used to determine which phone numbers are a potential fraud risk, and what the best communication method for a phone number is (voice, SMS).

You can get more out of your requests by including add-ons. Add-ons allow you to request detailed information about various aspects of a phone number that may not be included in a regular PhoneID request. To use add-ons, you must send your requests as application/json rather than application/x-www-form-urlencoded.

Available add-ons include:

  • Contact - allows you to retrieve the name and address associated with the phone number you submit, without requesting explicit consent from your end user.
  • Contact Plus - requires explicit consent from your end users, and once obtained, allows TeleSign to directly access a subscriber’s name and address on file with the carrier.
  • Contact Match - allows you to compare a name and address for a submitted phone number in your request with a name and address on file with the carrier and return a score referred to as a match score that tells you how close a match was found.
  • Device Info - allows you to provide an end-user phone number and receive its phone manufacturer and model to detect fraud or understand the value or risk of the device holder and adjust content and marketing strategies per device.
  • Number Deactivation - allows you to find out whether a phone number has been deactivated, when it was deactivated, and by which carrier the phone number was deactivated based on carriers’ phone number data and TeleSign’s proprietary analysis.
  • Subscriber Status allows you to provide an end-user phone number and receive their current carrier subscriber status (prepaid or postpaid; active, suspended, deactivated; account type; primary account holder; length of account tenure) to understand the strength, value or risk of a user.
  • Porting History - allows you to retrieve details about where a phone number was ported.
  • Porting Status - allows you to find out whether or not a phone number was ported to a carrier and who the current carrier is based on the mobile country code (MCC) and mobile network code (MNC) returned in the response.
  • Sim Swap - allows you to determine whether or not the SIM for the phone number has been swapped and how recently the swap occurred. TeleSign evaluates how likely it is that the SIM swap was for a fraudulent reason using a scale from 1-4.

You can include as many add-ons in a single request as you like.

You can read more about add-ons in the following sections:

Configure an Add-on

To enable any add-on, speak with your Technical Account Manager (TAM).

Use an Add-on

You use an add-on in the body of your request like so:

POST Request for the Contact Add-on with application/json
POST https://rest-ww.telesign.com/v1/phoneid/15555551212 HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Date: Thu, 12 Oct 2017 14:11:09 GMT
Content-Type: application/json 


{  
		“addons”: {
 			“contact”: {}
		}
}
Add-on API Request Term
Contact "contact":{}
Contact Plus "contact_plus":{zip_code}"
Contact Match Any of "contact_match":{ "first_name": "Peter", "last_name": "Petersen", "address": "1444 S. Alameda Street Los Angeles", "city": "San Jose", "postal_code": "95120", "state": "CA", "country": "USA" }
Device Info "device_info":{}
Number Deactivation "number_deactivation":{}
Subscriber Status "subscriber_status":{}
Porting History "porting_history":{}
Porting Status "porting_status":{}
Sim Swap "sim_swap":{}

Try an Add-on with cURL

cURL is a software project that provides a library and command-line tool for transferring data using various protocols. You can use it to quickly do API calls if the API you query allows basic authentication. cURL is available for Mac and Windows. If you have never used it, you can learn about how to install it from these sources:

After you have it installed, you would send this cURL command with your add-on included (you must replace complete-number in the --request line, the CUSTOMER_ID, and API_KEY values with your customer ID and API key, or it will not work):

curl --request POST https://rest-ww.telesign.com/v1/phoneid/<complete-number> --header "Content-Type: application/json" --data '{"addons":{"contact":{}}}' --user "CUSTOMER_ID":"API_KEY"
curl --request POST https://rest-ww.telesign.com/v1/phoneid/<complete-number> --header "Content-Type: application/json" --data '{"addons":{"porting_history":{}}}' --user "CUSTOMER_ID":"API_KEY"

All Request and Response Parameters for Add-ons

This section describes the request parameters for add-ons. You use application/json to send your request, you can include any normal PhoneID parameters, and then whatever is required for the add-on you are interested in using. The add-on must be enabled to work.

Request Parameters

object
addons
object

You must have you Technical Account Manager enable this feature for use. The addons parameter allows you to receive information returned from Contact, Contact Plus, Contact Match, or Number Deactivation, depending on which add-ons you enable. You receive add-on information back along with standard PhoneID information.

contact
object

The Contact add-on allows you to retrieve the name and address associated with the phone number you submit, without requesting explicit consent from your end user. Information included in the response is the first name, last name, street address, city, state (or province), country, and zip code.

contact_plus
object

The Contact Plus add-on requires explicit consent from your end users, and once obtained, allows TeleSign to directly access a subscriber’s name and address on file with the carrier.

contact_match
object

Contact Match allows you to provide any information like first name, last name, address, postal code, state, or country and compare to information on file with the carrier and see how close a match there is.

current_location_plus
string

The Current Location Plus add-on provides you with roaming location or roaming status for a device.

device_info
string

Use this add-on to receive phone manufacturer and model to detect fraud or understand the value or risk of the device holder and adjust content and marketing strategies per device.

number_deactivation
string

The Number Deactivation add-on allows you to find out whether a phone number has been deactivated, when it was deactivated, and by which carrier the phone number was deactivated based on carriers’ phone number data and TeleSign’s proprietary analysis. This information is returned in addition to the standard PhoneID API information.

subscriber_status
string

This add-on allows you to provide an end-user phone number and receive their current carrier subscriber status (prepaid or postpaid; active, suspended, deactivated; account type; primary account holder; length of account tenure) to understand the strength, value or risk of a user.

porting_history
string

This add-on allows you to find out at what point and where a phone number was ported to. If a phone number was ported in the last 90 days from one carrier to another, available details are provided in the response.

porting_status
string

This add-on allows you to find out whether or not a phone number was ported to a carrier and who the current carrier is based on the mobile country code (MCC) and mobile network code (MNC) returned in the response.

sim_swap
string

The Sim Swap add-on allows you to determine whether or not the SIM for the phone number has been swapped and how recently the swap occurred. TeleSign evaluates how likely it is that the SIM swap was for a fraudulent reason using a scale from 1-4.

Response Parameters

Response parameters you get back include:

  • All standard PhoneID information you would get back from a regular request to the PhoneID API.
  • All information for each add-on you included in your request
object
reference_id
string

A 32-digit hex value used to identify the web service requests. The value is unique to each web service request, is randomly generated by TeleSign, and is returned in the response message immediately following the web service request.

phone_type
string

One of the phone type codes.

description
string

Text describing the phone type.

contact
object

You will only see this in your response if you used the contact add-on.

address1
string

The name of the street for the address

address2
string

Unit or Suite number for the address

address3
string

Town, City, or State

address4
string

Postal Code

city
string

The city where the address is located

country
string

The country where the address is located

first_name
string

The first name of the person associated with the address

last_name
string

The last name of the person associated with the address

email_address
string

The email address of the person

state_province
string

State or province where the address is located

status
object

An object containing details about the success or failure of your request.

zip_postal_code
string

Postal code for the address

contact_plus
object

You will only see this in your response if you used the contact plus add-on.

This add-on provides the same response content as you would get back for the contact add-on, but the data is higher quality. If you want to see what is returned, refer to the contact add-on.

contact_match
object

You will only see this in your response if you used the contact match add-on.

address_score
string

A score from 0-100 showing you how close a match the address information you sent is to what is on file. It is recommended that scores greater than or equal to 90 be considered a ‘pass’ meaning it is enough of a match for validation. If you receive a score of -1 it means the match was not available.

first_name_score
string

A score from 0-100 showing you how close a match the first name information you sent is to what is on file. It is recommended that scores greater than or equal to 90 be considered a ‘pass’ meaning it is enough of a match for validation. If you receive a score of -1 it means the match was not available.

last_name_score
string

A score from 0-100 showing you how close a match the last name information you sent is to what is on file. It is recommended that scores greater than or equal to 90 be considered a ‘pass’ meaning it is enough of a match for validation. If you receive a score of -1 it means the match was not available.

status
object
date_of_birth_score
string

This is only available for numbers from Brazil and the UK. If you included a date of birth (DOB) in your request to the Contact Match service, you will get back a DOB score. This is a score from 0-100 showing you how close a match the date of birth information you sent is to what is on file. It is recommended that scores greater than or equal to 90 be considered a ‘pass’ meaning it is enough of a match for validation. If you receive a score of -1 it means the match was not available.

device_info
object

You will only see this in your response if you used the device info add-on.

make
string

A string indicating the manufacturer (the brand) of the device associated with the mobile number. Coverage - Mobile phones. USA: Sprint, T-Mobile. Canada: Bell, Rogers, Telus. India: Vodafone.

model
string

A string indicating the model of the device associated with the mobile number. Coverage - Mobile phones. USA: Sprint, T-Mobile. Canada: Bell, Rogers, Telus. India: Vodafone.

imei
string

The international mobile equipment identity (IMEI) for the device associated with the mobile number. An IMEI is a 15 digit number unique to each device, but in the response, the hashed value is returned up to 120 characters. Coverage - Hashed IMEI value up to 120 characters. Mobile phones. USA: T-Mobile, Verizon. Canada: Bell, Rogers, Telus.

status
object
number_deactivation
object

You will only see this in your response if you used the number deactivation add-on.

carrier_name
string

A string indicating the name of the current carrier for the phone.

last_deactivated
string

When the phone was last deactivated (if it was).

tracking_since
string

When the phone number first started being tracked for deactivation status.

status
object
subscriber_status
object

You will only see this in your response if you used the subscriber status add-on.

account_activation_date
string

The date the account first became active.

account_type
string

A string indicating the maximum amount of time in months the subscriber may have had their account. Coverage - All phone types. USA: Sprint, T-Mobile, Verizon.

account_tenure_max
integer

An integer indicating the maximum amount of time in months the subscriber may have had their account. Coverage - All phone types. USA: Sprint, T-Mobile, Verizon.

account_tenure_min
integer

An integer indicating the minimum amount of time in months the subscriber may have had their account.

primary_account_holder
boolean

A boolean value indicating whether the phone number is the primary phone number of the account or not. Coverage - Mobile phones. USA: Sprint, T-Mobile, Verizon. Canada: Telus.

account_status
string

A string indicating whether an account is ‘active’ or ‘suspended’ or ‘deactivated’. Coverage - All phone types. USA: Sprint, T-Mobile, Verizon. Canada: Bell, Rogers, Telus. India: Vodafone.

contract_type
string

A string indicating whether an account is ‘postpaid’ (an account where service is provided by prior arrangement with a mobile network operator, and the subscriber pays at the end of each month) or ‘prepaid’ (an account where the subscriber pays for the service up front). Coverage - All phone types. USA: Sprint, T-Mobile, Verizon. Canada: Bell, Rogers, Telus. India: Vodafone.

status
object
porting_history
object
carrier_current
string

The name of the current carrier for the phone number you provided.

carrier_previous
string

The name of the carrier before the phone number was ported to the new carrier.

mcc_carrier_current
string

The mobile country code for the current carrier. This field can include multiple values for MCC.

mcc_carrier_previous
string

The mobile country code for the previous carrier. This field can include multiple values for MCC.

mnc_carrier_current
string

The mobile network code for the current carrier. This field can include multiple values for MNC.

mnc_carrier_previous
string

The mobile network code for the previous carrier. This field can include multiple values for MNC.

phone_type_current
string

The phone type currently associated with the phone number.

phone_type_previous
string

The phone type previousl associated with the phone number.

port_date
string

The date the phone number was ported to a new carrier.

status
object
porting_status
object
mcc_current
string

The mobile country code (MCC) for the current carrier associated with the device. The MNC is used in conjunction with the MCC to uniquely identify a carrier.

mnc_current
string

The mobile network code (MNC) for the current carrier associated with the device. The MNC is used in conjunction with the MCC to uniquely identify a carrier.

ported
boolean

Ported indicates whether the number was ported or not.

status
object
sim_swap
object
swap_date
string

If the number has been sim swapped, the date of the swap appears here.

swap_time
string

If the number has been sim swapped, this field indicates at what time the swap occurred.

risk_indicator
string

This field shows TeleSign’s assessment for how likely it is to have been a swap that was carried out for a fraudlent purpose. The response is a number 1-4. 1 - (very low) swap did not occur or it occurred in the last 15+ days. 2 - (low) swap occurred some time between the last 3 and 14 days. 3 - (medium) swap occurred in the last 72 hours. 4 - (high) swap occurred same day.

status
object

Contact

The Contact add-on allows you to retrieve the name and address associated with the phone number you submit, without requesting explicit consent from your end user. The information included by this add-on is details about the subscriber who owns the phone number:

  • First Name
  • Last Name
  • Street Address
  • City
  • State (or Province)
  • Country
  • ZIP Code
  • Email Address

Contact is discussed in the following sections:

Example Request and Response for Contact

POST Request for Contact
POST https://rest-ww.telesign.com/v1/phoneid/15555551212 HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Date: Thu, 12 Oct 2017 14:11:09 GMT
Content-Type: application/json 


{  
		“addons”: {
 			“contact”: {}
		}
}
Contact Response Body
{
  "contact": {
    "address1": "2432 CHIMNEY POINT LN",
    "address2": "",
    "address3": "",
    "address4": "",
    "city": "LEXINGTON",
    "country": "",
    "first_name": "MYLA",
    "last_name": "JONES",
    "state_province": "KY",
    "status": {
      "code": 2800,
      "description": "Request successfully completed"
    },
    "zip_postal_code": "40509",
    "email_address": "email@acme.com"
  }
}

Contact Plus

The Contact Plus add-on requires explicit consent from your end users, and once obtained, allows TeleSign to directly access a subscriber’s name and address on file with the carrier. The information included by this add-on is details about the subscriber who owns the phone associated with the phone number:

  • First Name
  • Last Name
  • Street Address
  • City
  • State (or Province)
  • Country
  • ZIP Code
  • Email address

Consent for Contact Plus

In order to use the Contact Plus add-on, you must obtain explicit consent from your end users. In your application, create a message asking if it is okay to verify the end user’s name, address, and mobile number with a mobile service provider. An example of the message might be ‘You agree that we may verify your number in order to verify your identity, and you consent to having this information reviewed, disclosed, and compared for this purpose.’ Another example might be to provide them with a written notice of your Terms and Conditions (including this request for consent) that reads ‘I have read and agree with the Terms and Conditions, including the disclosure of my personal information about me by third parties for the purposes of identity verification.’

Example Request and Response for Contact Plus

POST Request for Contact Plus
POST https://rest-ww.telesign.com/v1/phoneid/15555551212 HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Date: Thu, 12 Oct 2017 14:11:09 GMT
Content-Type: application/json 

{  
		“addons”: {
 			“contact_plus”: {"billing_postal_code": "40509"}
		}
}
Contact Plus Response Body
{
   "contact_plus": {
      "address1": "2432 CHIMNEY POINT LN",
      "address2": "",
      "address3": "",
      "address4": "",
      "city": "LEXINGTON",
      "country": "",
      "email_address": "myla@xyz.com",
      "first_name": "MYLA",
      "last_name": "JONES",
      "state_province": "KY",
      "status": { 
         "code": 2800,
         "description": "Request successfully completed"
      },
      "zip_postal_code": "40509"
   },

}

Contact Match

Contact Match is an optional add-on offered as part of the PhoneID API. It allows you to compare a name and address for a submitted phone number in your request with a name and address on file with the carrier and return a score referred to as a match score that tells you how close a match was found.

Match Score

A match score is a value ranging from 0-100 that tells you how close a match you have between the name and address you provide and what is on file with the carrier for submitted phone numbers. It is recommended that scores greater than or equal to 90 be considered a ‘pass’ meaning it is enough of a match for validation. If you receive a score of -1 it means the match was not available.

Info Returned by Contact Match

Contact Match is an add-on to the PhoneID API. When you use this add-on, you get back all the information you would get back from a standard PhoneID request, all the information for any other add-ons you may be using, and for Contact Match, you get back the following information:

  • first_name_score - an integer representing the match score for the first name of the contact you are looking up
  • last_name_score - an integer representing the match score for the last name of the contact you are looking up
  • address_score - an integer representing the match score for the address of the contact you are looking up
  • date_of_birth_score - an integer representing the match score for the date of birth of the person you are looking up. This is only available for phone numbers from Brazil and the UK. If you do not include the date_of_birth parameter in your request this will not come back in the results
  • status - an object containing details about the status of your request

Consent for Contact Match

In order to use the Contact Match add-on, you must obtain implicit consent from your end users. In your application/property (online platform), create a message informing your end users that by signing up for this service they accept your Terms of Service and Privacy Policy. Make it clear in the Personal Data section of your Privacy Policy that their personal data is shared with third parties including but not limited to identity verification services, service providers, government entities, utilities, public records, credit bureaus, telecomm providers, property files and watch lists. Include a statement like “By signing up for this service you acknowledge that we may disclose your name, address, email, and mobile number to third parties in connection with the processing of identity or account verification, fraud detection or as may otherwise be required by applicable law”.

Your app should include a way to present this request for consent alongside the details of what personal data you may share.

Example Request and Response for Contact Match

POST Request for Contact Match
POST https://rest-ww.telesign.com/v1/phoneid/15555551212 HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Date: Thu, 12 Oct 2017 14:11:09 GMT
Content-Type: application/json 

{
    "addons": {
        "contact_match": {
            "first_name": "Peter",
            "last_name": "Petersen",
            "address": "1444 S. Alameda Street Los Angeles",
            "city": "San Jose",
            "postal_code": "95120",
            "state": "CA",
            "country": "USA",
            "date_of_birth":"1978-08-22"
        }
    }
}
Contact Match Response Body
    'contact_match': {
        'address_score': 100,
        'first_name_score': 100,
        'last_name_score': 100,
        'date_of_birth_score': 100,
        'status': {
            'code': 2800,
            'description': 'Request successfully completed.'
        }
    }
Contact Match Error Response
    "contact_match": {
        "status": {
            "code": 2806,
            "description": "contact_match add-on is not enabled.",
        }
    }
Contact Match Add-on No Match Response
    "contact_match": {
        "status": {
            "code": 2805,
            "description": "No contact_match add-on information for phone number."
        }
    }
Contact Match Add-on Out of Coverage Error Response
    "contact_match": {
        "status": {
            "code": 2803,
            "description": "Phone number out of contact_match add-on coverage."
        }
    }

Contact Match for Brazil

If you are using Contact Match for Brazil, the following rules apply:

  • You can validate first name, last name, address, and date of birth for a submitted phone number. Matching is done for the address including street name, street number, block number, apartment number, and neighborhood (bairro).
  • It is not possible to validate zip code, city, state and country.
  • The match score can come back from 0-100 to tell you how close a match you have between the name and address you provide and what is on file with the carrier for submitted phone numbers.
  • When you submit a name for the first_name parameter, it should contain only one name.
  • When you submit a name for the last_name parameter, you can include multiple names.

For example, say you want a match for someone whose full name is “LUIS CARLOS TEIXEIRA BRITO JUNIOR” and address “RUA COSTA ESMERALDA 50 BL 14 APT 22 CENTRO”.

Example for Multiple Names
POST https://rest-ww.telesign.com/v1/phoneid/15555551212 HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Date: Thu, 12 Oct 2017 14:11:09 GMT
Content-Type: application/json 

{
    "addons": {
        "contact_match": {
            "first_name": "Luis",
            "last_name": "Carlos Teixeira Brito Junior",
            "address": "RUA COSTA ESMERALDA 50 BL 14 APT 22 CENTRO"
        }
    }
}
  • For address parameters, you must format the address like: “streetName[space]streetNumber[space]BL[space]blNumber[space]APT[space]aptNumber[space]neighborhoodName”

Contact Match for China

If you are using Contact Match for China, the following rules apply:

  • You can validate first name and last name for a submitted phone number and it is not possible to validate address.
  • You must provide name matching information for first_name and last_name parameters using Chinese characters.
  • You cannot match for anything besides first name, last name, and phone number, so do not provide other information in your match request.
  • The score is either all or nothing. If there is a match between the first and last name you provide and what is on file with the carrier, the score returned is 100. Otherwise, the score returned is 0.

Contact Match for Switzerland

If you are using Contact Match for Switzerland, the following rules apply:

  • You can validate for first name, last name, and address for submitted phone number.
  • When you send information for the address parameter, you should include street name and the city.
  • You cannot validate zip code and state.

Contact Match for the UK

If you are using Contact Match for the UK (Telefonica only), the following rules apply:

  • You can validate for first name, last name, date of birth, and address for a submitted phone number.
  • When you send information for the address parameter, your information should include the house name or house number.
  • For the postal_code parameter you should include the UK post code.
  • You do not need to provide other information such as city and country in your match request, it is optional.
  • The score is either all or nothing. If there is a match between first name, last name and the address you provide and what is on file with the carrier, the score returned is 100. Otherwise, the score returned is 0.

Device Info

The Device Info add-on allows you to provide an end-user phone number and receive its phone manufacturer and model to detect fraud or understand the value or risk of the device holder and adjust content and marketing strategies per device.

Device Info for Switzerland

If you are using Device Info for Switzerland, the following rules apply:

  • The fields you can get back for Switzerland (Swisscom only) phone numbers are:
    • imei
    • make
    • model

Example Request and Response for Device Info

POST Request for Device Info
POST https://rest-ww.telesign.com/v1/phoneid/15555551212 HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Date: Thu, 12 Oct 2017 14:11:09 GMT
Content-Type: application/json 

{  
		“addons”: {
 			“device_info”: {}
		}
}
Device Info Response Body
{
  "device_info": {
    "make": "APPLE",
    "model": "A1784",
    "imei": "355376084044028",
    "status": {
      "code": 2800,
      "description": "Request successfully completed"
    }
  }
}

Number Deactivation

The Number Deactivation add-on allows you to find out whether a phone number has been deactivated, when it was deactivated, and by which carrier the phone number was deactivated based on carriers’ phone number data and TeleSign’s proprietary analysis. This information is returned in addition to the standard PhoneID API information.

The Number Deactivation add-on allows you to get information from the Number Deactivation API without having to implement it separately. The information returned includes:

  • Number Deactivation
    • Carrier name - carrier which deactivated the phone number last time
    • Last Deactivated Timestamp - when the phone number was last deactivated
  • Tracking Since Timestamp - the timestamp for when carrier phone numbers started being tracked for number deactivation events
  • Status

Example Request and Response for Number Deactivation

Number Deactivation Request Body
POST https://rest-ww.telesign.com/v1/phoneid/15555551212 HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Date: Thu, 12 Oct 2017 14:11:09 GMT
Content-Type: application/json

{
    "addons": {
        "number_deactivation": {}
    }
}
Number Deactivation Response Body
"number_deactivation": {
	  "carrier_name": "Verizon",
  	"last_deactivated": "2016-04-05T00:00:00Z",
  	"status": {
    		"code": 2800,
      	"description": "Request successfully completed"
    },
  	"tracking_since": "2014-10-06T00:00:00Z"
}
Number Deactivation Error Response
{
    "number_deactivation": {
        "status": {
            "code": 2603,
            "description": "Phone number out of number_deactivation add-on coverage." 
        },
    }
}

Subscriber Status

Subscriber Status is an optional add-on offered as part of the PhoneID API. This add-on allows you to provide an end-user phone number and receive their current carrier subscriber status (prepaid or postpaid; active, suspended, deactivated; account type; primary account holder; length of account tenure) to understand the strength, value or risk of a user.

Information Returned by Subscriber Status

Subscriber Status is an add-on to the PhoneID API. When you use this add-on, you get back all the information you would get back from a standard PhoneID request, all the information for any other add-ons you may be using, and for Subscriber Status for the US you would (check the differences by location) get back the following information:

  • account_type - whether the account is for an individual or an organization
  • account_tenure_max - the maximum amount of time in months the subscriber may have had their account (carriers often provide a range rather than a specific number of months). This may not come back in every response.
  • account_tenure_min - the minimum amount of time in months the subscriber may have had their account (carriers often provide a range rather than a specific number of months). This may not come back in every response.
  • primary_account_holder - whether the phone number is the primary phone number of the account or not
  • account_status - whether the account is active or not
  • contract_type - whether the account is post-paid or pre-paid
  • status - standard status information that tells you whether your query about subscriber status was successful or not
  • account_activation_date - the date the account was activated. It may not come back in every response.

Subscriber Status for Brazil

If you are using Subscriber Status for Brazil, the following rules apply:

  • The fields you can get back for Brazil phone numbers are:
    • account_tenure_min
    • account_tenure_max
    • account_status
    • contract_type
    • account_activation_date

Subscriber Status for Canada

If you are using Subscriber Status for Canada, the following rules apply:

  • The fields you can get back for Canada phone numbers are:
    • account_type
    • primary_account_holder
    • account_status
    • contract_type
    • account_activation_date - only on demand, speak with your TAM to learn more.

Subscriber Status for China

If you are using Subscriber Status for China, the following rules apply:

  • The fields you can get back for China phone numbers are:
    • account_tenure_min
    • account_tenure_max
    • account_status

Subscriber Status for India (Vodafone Only)

If you are using Subscriber Status for India, the following rules apply:

  • The fields you can get back for India phone numbers are:
    • account_status
    • contract_type

Subscriber Status for Switzerland

If you are using Subscriber Status for Switzerland (Swisscom only), the following rules apply:

  • The fields you can get back for Switzerland (Swisscom only) phone numbers are:
    • account_tenure_min
    • account_tenure_max
    • account_status
    • contract_type
    • account_activation_date

Example Request and Response for Subscriber Status

POST Request for Subscriber Status
POST https://rest-ww.telesign.com/v1/phoneid/15555551212 HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Date: Thu, 12 Oct 2017 14:11:09 GMT
Content-Type: application/json 

{  
		“addons”: {
 			“subscriber_status”: {}
		}
}
Response Body for Subscriber Status
{
  "subscriber_status": {
    "account_activation_date": "2014-10-08",
    "account_type": "individual",
    "account_tenure_max": 6,
    "account_tenure_min": 3,
    "primary_account_holder": True,
    "account_status": "active",
    "contract_type": "postpaid",
    "status": {
      "code": 2800,
      "description": "Request successfully completed"
    }
  }
}

Porting History

The Porting History add-on allows you to find out at what point and where a phone number was ported to. If a phone number is ported in the last 90 days from one carrier to another, the information you get in a response includes:

  • Current and previous carrier name
  • Current and previous MCC (mobile country code)
  • Current and previous MNC (mobile network code)
  • Current and previous phone type
  • The date the number was ported
  • The combination MCC and MNC uniquely identify a mobile network operator (carrier)
  • Porting History add-on information is available for US phone numbers ported in the last 90 days

Example Request and Response for Porting History

POST Request for Porting History
POST https://rest-ww.telesign.com/v1/phoneid/15555551212 HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Date: Thu, 08 Nov 2018 14:11:09 GMT
Content-Type: application/json 

{
  "addons": {
    "porting_history": {}
  }
}
Response Body for Porting History
{
  "porting_history": {
    "carrier_current": "Sprint Spectrum, L.P.",
    "carrier_previous": "US Cellular Corp.",
    "mcc_carrier_current":"310",
    "mcc_carrier_previous":"310",
    "mnc_carrier_current": "120",
    "mnc_carrier_previous": "160",
    "phone_type_current": "MOBILE",
    "phone_type_previous": "MOBILE",
    "port_date": "2018-08-26T16:33:19Z",
    "status": {
      "code": 2800,
      "description": "Request successfully completed"
      }
    }
  }
}
Response Body When a Phone Number Was Not Ported in the Last 90 Days
{
  "porting_history": {
    "status": {
      "code": 2805,
      "description": "No porting_history add-on information for phone number."
    }
  }
}
Response Body When Porting History Add-on is Not Enabled
{
  "porting_history": {
    "status": {
      "code": 2806,
      "description": "porting_history add-on is not enabled."
    }
  }
}

Porting Status

The Porting Status add-on allows you to find out if a phone number was ported or not and what carrier currently has the number. The information you get in a response includes the current MCC (mobile country code) and the current MNC (mobile network code).

Availability of Porting Status

TeleSign offers porting status information for phone numbers in these countries:

  • Afghanistan
  • Albania
  • Algeria
  • American Samoa
  • Andorra
  • Angola
  • Anguilla
  • Antigua and Barbuda
  • Argentina
  • Aruba
  • Australia
  • Austria
  • Bahamas
  • Bahrain
  • Bangladesh
  • Barbados
  • Belgium
  • Belize
  • Benin
  • Bermuda
  • Bhutan
  • Bolivia
  • Bosnia and Herzegovina
  • Botswana
  • Brunei Darussalam
  • Bulgaria
  • Burkina’Faso
  • Burundi
  • Brazil
  • Cape Verde
  • Cayman Islands
  • Central African Republic
  • Chad
  • Chile
  • China
  • Colombia
  • Comoros
  • Congo
  • Cook Islands
  • Egypt
  • Ethiopia
  • France
  • Germany
  • Ghana
  • India
  • Indonesia
  • Iran
  • Italy
  • Japan
  • Kazakhstan
  • Malaysia
  • Mexico
  • Morocco
  • Nigeria
  • Pakistan
  • Peru
  • Philippines
  • Poland
  • Russia
  • Saudi Arabia
  • South Korea
  • Spain
  • Taiwan
  • Thailand
  • Turkey
  • Ukraine
  • United Kingdom
  • United States
  • Vietnam

Example Request and Response for Porting Status

This section provides examples of a request with the porting status add-on and possible responses.

Porting Status Request
POST https://rest-ww.telesign.com/v1/phoneid/15555551212 HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Date: Thu, 08 Nov 2018 14:11:09 GMT
Content-Type: application/json 

{
    "addons": {
        "porting_status": {}
    }
}

Here is an example of a successful response body:

Porting Status Successful Response Body
{
  "porting_status": {
    "mcc_current": "310",
    "mnc_current": "01",
    "ported": true,
    "status": {
      "code": 2800,
      "description": "Request successfully completed"
    }
  }
}

This is the response body when the request times out:

Porting Status Response Body for a Timeout
{
    "porting_status": {
        "status": {
            "code": 2811,
            "description": "Request processing timeout.",
        }
    }
}

Here is an example response body when no porting information is found:

Porting Status Response Body for No Information Found
{
  "porting_status": {
    "status": {
      "code": 2805,
      "description": "No porting_status add-on information for phone number."
    }
  }
}

Here is an example response body when the phone number is out of coverage. This means it is too far from a cellular antenna, in a restricted area that blocks signals, or it may be off.

Response Body When the Phone Number is Out of Coverage
{
  "porting_status": {
    "status": {
      "code": 2803,
      "description": "Phone number out of porting_status add-on coverage."
    }
  }
}

SIM Swap

The SIM Swap add-on allows you to find out whether or not the SIM for the phone number has been swapped and if so, at what point. TeleSign evaluates how likely it is that the SIM swap was for a fraudulent reason using a scale from 1-4. The scale is provided as part of the risk_indicator parameter in the response. Possible values are:

  • 1 - (very low risk) A swap did not occur, or it occurred more than 15 days ago.
  • 2 - (low risk) A swap occurred some time between the last 3 and 14 days.
  • 3 - (medium risk) A swap occurred in the last 72 hours.
  • 4 - (high risk) A swap occurred the same day.

The information you get in a response includes:

  • Risk indicator
  • Swap date
  • Swap time (if available)

Availability of SIM Swap

SIM Swap is available in the US for mobile T-mobile phone numbers.

Example Request and Response for SIM Swap

This section provides examples of a request to use the SIM Swap add-on, and various responses.

A SIM Swap request looks like this:

SIM Swap Request
POST https://rest-ww.telesign.com/v1/phoneid/15555551212 HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Date: Thu, 08 Nov 2018 14:11:09 GMT
Content-Type: application/json 

{
    "addons": {
        "sim_swap": {}
    }
}

Here is an example of a successful response body for SIM Swap:

Successful Response Body for SIM Swap
{
  "sim_swap": {
    "swap_date": "2018-09-05",
    "swap_time": "22:00:00",
    "risk_indicator": 1,
    "status": {
      "code": 2800,
      "description": "Request successfully completed"
    }
  }
}

This is an example error response body for when a SIM Swap request times out:

Error Response Body for a Timeout
{
    "sim_swap": {
        "status": {
            "code": 2811,
            "description": "Request processing timeout.",
        }
    }
}

Here is an example error response body for when no information is found for SIM Swap:

Error Response Body for No Information Found
{
  "sim_swap": {
    "status": {
      "code": 2805,
      "description": "No sim_swap add-on information for phone number."
    }
  }
}

Here is an example error response for when a phone number is out of coverage. Out of coverage means the phone is turned off, or too far from a cellular tower.

Error Response Body for Phone Number Out of Coverage
{
  "sim_swap": {
    "status": {
      "code": 2803,
      "description": "Phone number out of sim_swap add-on coverage."
    }
  }
}

Status Codes

Status Code Description
2800 Request successfully completed
2801 Invalid request addons parameter: {parameter_name}.
2802 name of add-on add-on temporarily unavailable.
2803 Phone number out of name of add-on add-on coverage.
2804 Phone number not applicable in name of add-on add-on.
2805 No name of add-on add-on information for phone number.
2806 Name of add-on add-on is not enabled.
2807 Some parameters submitted in the request are not valid.
2808 Invalid Request: {parameter_name} parameter is missing or empty.
2809 Billing Postal Code does not match contact_plus add-on information for phone number.
2810 Request process failed during data collection.
2811 Request processing timeout.
2812 name of add-on exceeded transaction hard cap. Request denied.

Next Steps

This section offers some suggestions for next steps to take.