Phone ID - Identity attributes: Subscriber Status

📘

NOTE:

To add this feature to your account, contact a Telesign expert. This feature is available for full-service accounts only.

The Subscriber Status identity attribute 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 better understand their value or risk.

Information returned by Subscriber Status

  • 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 - Contains properties explaining the processing status of your request.
  • account_activation_date - The date the account was activated. It may not come back in every response.

Subscriber Status for Brazil

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

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

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)

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

  • account_status
  • contract_type

Subscriber Status for Switzerland

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

Request

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)

{
  "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
addonsobjectThis parameter allows you to receive information returned from your enabled identity attributes. Contact our Customer Support Team to add this feature.
addons.subscriber_statusstringInclude this parameter to initiate use of the Subscriber Status identity attribute.

Subscriber Status response

PropertyTypeDescription
reference_idstringA 32-digit hex value used to identify a web service request. The value is unique to each web service request and is randomly generated by Telesign.
phone_typestringOne of the phone type codes.
descriptionstringText describing the phone type.
subscriber_statusobjectContains sub-properties related to the Subscriber Status identity attribute.
subscriber_status.account_activation_datestringThe date the account first became active.
subscriber_status.account_typestringWhether the account belongs to an individual, an organization, or a government.
subscriber_status.account_tenure_maxintegerThe 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_minintegerThe minimum amount of time in months the subscriber may have had their account.
subscriber_status.primary_account_holderbooleanWhether 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_statusstringWhether an account is 'active', 'suspended', or 'deactivated'. Coverage - All phone types. USA: Sprint, T-Mobile, Verizon. Canada: Bell, Rogers, Telus. India: Vodafone.
subscriber_status.contract_typestringWhether 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 numeric code indicating the processing status of your request.
subscriber_status.status.descriptionstringText explaining what the error or status code means.