Phone ID - Identity attributes: Subscriber Status

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

Parameter

Type

Description

addons

object

You 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_status

string

Include this parameter to initiate use of the Subscriber Status identity attribute.

Subscriber Status response

Property

Type

Description

reference_id

string

A 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_type

string

One of the phone type codes.

description

string

Text describing the phone type.

subscriber_status

object

Contains sub-properties related to the Subscriber Status identity attribute.

subscriber_status.account_activation_date

string

The date the account first became active.

subscriber_status.account_type

string

Whether the account belongs to an individual, an organization, or a government.

subscriber_status.account_tenure_max

integer

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_min

integer

The minimum amount of time in months the subscriber may have had their account.

subscriber_status.primary_account_holder

boolean

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_status

string

Whether 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_type

string

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.status

object

subscriber_status.status.code

string

A numeric code indicating the processing status of your request.

subscriber_status.status.description

string

Text explaining what the error or status code means.


Did this page help you?