PhoneID API - Add-ons: 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 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

ParameterTypeDescription
addonsobjectYou 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.
addons.subscriber_statusstringThis 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.

Subscriber Status Response

PropertyTypeDescription
reference_idstringA 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_typestringOne of the [phone type code](https://enterprise.telesign.com/docs/codes-languages-and-time-zones#section-phone-type-codes\).
descriptionstringText describing the phone type.
subscriber_statusobjectYou will only see this in your response if you used the subscriber status add-on.
subscriber_status.account_activation_datestringThe date the account first became active.
subscriber_status.account_typestringA 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.
subscriber_status.account_tenure_maxintegerAn 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.
subscriber_status.account_tenure_minintegerAn integer indicating the minimum amount of time in months the subscriber may have had their account.
subscriber_status.primary_account_holderbooleanA 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.
subscriber_status.account_statusstringA 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.
subscriber_status.contract_typestringA 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.
subscriber_status.statusobject
subscriber_status.status.codestringA status or error code describing what happened after your request.
subscriber_status.status.descriptionstringA brief description of what the error or status code means.

Did this page help you?