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

Subscriber Status Response