Subscriber Status Add-on

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 our Customer Support Team 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": "2017-05-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"
    }
  }
}
Subscriber Status 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.

Subscriber Status Response
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.

subscriber_status
object

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