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
addonsobjectYou must have your Technical Account Manager enable this feature for use. This parameter allows you to receive information returned from your enabled identity attributes.
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.