Subscriber Detail¶

The subscriber detail interface is used to query the billing system for more detailed information on a specific subscriber. The subscriber’s unique id (which was obtained during search) is used for retrieval. The subscriber detail requires all optional fields that were available in subscriber search, plus other billing information fields.

Responses are expected to be JSON.

Subscriber Detail Parameters (HTTP GET)¶

The lookup is done using HTTP GET with the following parameters:

Element Name	Description
id	Unique id of subscriber
key	Key used for securing query pages. This is same key as used in search

The subscriber’s unique id would have been obtained from using the Subscriber Search interface defined previously. The id could be cached from a search beforehand, so if an id does not match an error should be returned.

Response JSON¶

The JSON response is an object with the following properties:

Property Name	Description
error	If there is an error this contains a short description of the problem retrieving the customer info. If there was no error this should be set to null
customer	A customer object. If there is no error set then this is used as the result for the given customer id

Customer Object¶

all fields except company_id are required to be present (only name, or the combination of firstname and lastname should be used, however). If a value is unavailable or does not apply, then it should be set to null:

Property Name	Type	Description
name	string	name of subscriber. If this is used then firstname and lastname should not be included.
firstname	string	Firstname of subscriber. This this is used then name should not be included
lastname	string	Lastname of subscriber. This this is used then name should not be included
username	string	Username of subscriber in the billing web portal, if available
id	string	Unique id of subscriber. This does not have to be numeric.
status	string	Status of subscriber which must be one of the following values: ‘active’ - services are all active ‘disabled’ - one or more services are disabled (possibly due to non-payment) ‘cancelled’ - account has been shut-off and not intended for re-activation
phone	string	Primary phone number of subscriber. The value is expected to numeric, other characters will be removed.
postalcode	string	Postal/zip code of subscriber.
email	string	Billing email address of subscriber. This is where statements and other correspondence would be sent
company_id	string	companyid of subscriber (if applicable). This field may be omitted if it is unused
notes	string	Non-critical customer-specific notes. This isn’t generally information that needs action taken (or notes from tickets) but basic non-standard account information.
critical_notes	string	Important information about an account. This can be temporary and will be displayed prominently to the technician looking up the account.
businessname	string	If this is a business account then then this is the name of the business. This should be null otherwise. Both the businessname and name fields can be used at the same time on a business account
address	string	The billing address for the account
city	string	The city for the billing address on the account
state	string	The state for the billing address on the account
country	string	The country for the billing address on the account
Basic Billing Information
balance	numeric	The balance on the account, 0 if none
balance_overdue	numeric	The overdue portion of the balance on the account. This should be the same, or less than ‘balance’. If there is no amount overdue then this should be 0
balance_minimum_due_date	date	If there is a balance amount, this is the date it is due.
security_questions	object	A list of security questions and answers, where the question is the key, and the answer is the value.
statement_type	string	This may only be one of the values: none email paper other
auto_bill_type	string	This may only be one of the values: none credit card echeck paypal other
services	array	This is a list of Service Object
packages	array	This is a list of Package Object
other_info	array	This is a list of OtherInfo Object

Service Object¶

Property Name	Type	Description
name	string	Label for the service/equipment.
type	string	This may only one of the values: dialup email webhosting fixed_wireless hotspot dsl static_ip voip router fiber account_portal mdu
fields	object	The keys required for this vary depending on the service type. refer to service-definitions for a reference on parameters
extra_fields	object	Fields for service related information that is not covered by the required ‘fields’ keys.

Each service type has different required fields. These keys are requried, but if the value is unavailable it can be returned as either a blank string, or null. Required fields for each type:

dialup

username

password

dsl

line_number

username

password

ip_address

fixed_wireless

ip_address

equipment_type

mac_address

email

email_address

password

webhosting

domain

voip

line_number

hotspot

static_ip

ip

fiber

router

account_portal

mdu

Package Object¶

Property Name	Type	Description
name	string	Name of the package
period_price	numeric	The amount the subscriber pays each biling period for this package
period	numeric	The billing period for this package, in months
next_bill_date	date	When the user should next expect a bill / statement for their upcoming service
next_due_date	date	When the next bill / statement they recieve would be due
next_autobill_date	date	When the customer will be charged for the next bill / statement if autopay is enabled for the customer and this specific package
next_service_period_start_date	date	When the service period for the next bill starts. This is assumed to last for the duration of the period for this package

OtherInfo Object¶

Property Name	Type	Description
type	string	The type of other info. Currently the only supported type is ‘billing_link’

The OtherInfo object is to represent various types of customer data that don’t fit into the service or package category. Each type has required properties if that type is used. The available types are:

billing_link¶

This displays a custom link for this subscriber above the package and service section

Property Name	Type	Description
label	string	This will be used for the anchor link text and is the clickable link
url	string	The URL to which the link text (label) will open a new tab to
description	string	text displayed to the right of the link to describe what the link does

Exmaple other_info object with a ‘bililng_link’ type:

{
 'type': 'billing_link',
 'label':'Example Link',
 'url':'http://example.net',
 'description': 'Custom link for customer Joe Jones'
}

Example Responses¶

Example Error Response¶

Example query URL:

http://www.example.com/subscriberinfo.cgi?id=17541

Example HTTP response body with no matching id in the external system:

{'error': '',
 'customer': null
}

Example Success Response - no overdue balance¶

This account has no overdue balance. There is 1 package billed monthly with the statement sent out 5 days before the service period starts. This is due 5 days after the service period starts.

Example query URL:

http://www.example.com/subscriberinfo.cgi?id=54321

Example HTTP response body:

{'error': '',
 'customer': {
   'name': 'John Johnson',
   'username': 'jjohnson',
   'id': 54321,
   'phone': '8885551234',
   'postalcode': '45678',
   'email': 'myaddress@example.com',
   'notes': '',
   'critical_notes': '',
   'businessname': '',
   'address': '123 N. Main Street',
   'city': 'Orem',
   'state': 'UT',
   'country': 'USA',
   'balance': 0,
   'balance_overdue': 0,
   'balance_minimum_due_date': null,
   'security_questions': {'City born in': 'Gotham',
                          'First pet\'s name': 'Roger'},
   'statement_type': 'email',
   'auto_bill_type': 'credit card',
   'services': [{'name': 'DSL',
                 'type': 'dsl',
                 'fields': {'line_number': '8885552345',
                            'equipment_type': 'Acme Modem 123'},
                 'extra_fields': {'speed': '1Mbps'}}],
   'packages': [{'name': 'Affordable internet',
                 'period_price': 39.95,
                 'period': 1,
                 'next_service_period_start_date': '2015-11-01',
                 'next_bill_date': '2015-10-26',
                 'next_due_date': '2015-11-06'}]
 }
}

Example Success Response - Balance on account¶

Example query URL:

http://www.example.com/subscriberinfo.cgi?id=12345

Example HTTP response body:

{'error': '',
 'customer': {
   'name': 'Mike Michaelson',
   'username': 'mikem',
   'id': 12345,
   'phone': '8885552345',
   'postalcode': '56789',
   'email': 'mikem@example.com',
   'notes': '',
   'critical_notes': '',
   'businessname': '',
   'address': '234 N. Main Street',
   'city': 'Orem',
   'state': 'UT',
   'country': 'USA',
   'balance': 60.00,
   'balance_overdue': 30.00,
   'balance_minimum_due_date': '2015-10-06',
   'security_questions': {'Favorite number': '42',
                          'First pet\'s name': 'Frank'},
   'statement_type': 'email',
   'auto_bill_type': 'credit card',
   'services': [{'name': 'DSL',
                 'type': 'dsl',
                 'fields': {'line_number': '8885554444',
                            'equipment_type': 'Acme Modem 123'},
                 'extra_fields': {'speed': '1Mbps'}}],
   'packages': [{'name': 'Internet',
                 'period_price': 30.00,
                 'period': 1,
                 'next_service_period_start_date': '2015-11-01',
                 'next_bill_date': '2015-10-26',
                 'next_due_date': '2015-11-06'}]
 }
}

Subscriber Detail¶