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
Parameter | Type | Description |
---|---|---|
addons | object | You 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_status | string | 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. |
Subscriber Status Response
Property | Type | Description |
---|---|---|
reference_id | string | A 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_type | string | One of the [phone type code](https://enterprise.telesign.com/docs/codes-languages-and-time-zones#section-phone-type-codes\). |
description | string | Text describing the phone type. |
subscriber_status | object | You will only see this in your response if you used the subscriber status add-on. |
subscriber_status.account_activation_date | string | The date the account first became active. |
subscriber_status.account_type | string | A 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_max | integer | An 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_min | integer | An integer indicating the minimum amount of time in months the subscriber may have had their account. |
subscriber_status.primary_account_holder | boolean | A 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_status | string | A 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_type | string | A 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.status | object | |
subscriber_status.status.code | string | A status or error code describing what happened after your request. |
subscriber_status.status.description | string | A brief description of what the error or status code means. |
Updated 6 months ago