Subscriber Search

The subscriber search interface is intended to be used to query the billing system for a list of subscriber’s matching search criteria. A list of subscribers is returned, formatted as JSON, with basic subscriber information including their unique id.

Since customer management systems vary, not all supported search fields are required. If your billing system does not use the optional fields they may be omitted from search results. Name fields are required for search, and may be the “firstname” and “lastname” field, or a “name” field instead. If the customer management system stores the first and lastnames as separate fields then this should be used, otherwise the “name” field should be used instead.

Search Parameters (HTTP GET)

These parameters are always included for a search query, but are not search filters:

company_id	Unique companyid of subscriber, if applicable. This is used when there are multiple brands/companies in the billing, system. If this is not the case this field can be ignored.
key	Key (password) sent with every request to help identify the system sending the query. This is can be given to serverplus, or generated by serverplus. Combined with HTTPS and Access Control lists, a query page can be secured so unauthorized users cannot retrieve information.

Search filters:

Element Name	Required	Description
firstname	yes	Firstname of subscriber. This is requried if the “name” field is not used.
lastname	yes	Lastname of subscriber. This is requried if the “name” field is not used.
name	yes	Name of subscriber, this is required if first and last name fields are not used.
username	no	Username of subscriber in billing portal, if available.
email	no	Email address used for sending statments and other correspondance by the Customer Management system.
businessname	no	Name of business for business accounts
postalcode	no	Postal (zip) code for billing address
address	no	Billing address
city	no	City for the billing address
phone	no	Phone number(s) for the the billing address

All search filters have implied wildcards at the front and back of the string. A firstname parameter with the value ‘rob’ would make a SQL query similar to:

WHERE firstname like '%rob%'

Searches are required to be case-insensitive. Searching for a firstname of ‘rob’ should return the same results as when searching for a firstname of ‘ROB’.

Response JSON

Responses are JSON encoded and are an object with the following properties:

Element Name	Description
error	If there was an error this is a string describing the problem while searching. If this is set then any results are ignored. If there were no error this property does not need to be included, or can be set to null
customers	Required. An array of customer objects. If there were no matches then this should be an empty array. Properties for the customer object are explained below. If there were more than 200 records matched, only the first 200 records should be returned.
number_of_results	This is the number of records that matched the search results. If there were 200 or less matching records than this should be the same number as the length of the ‘customers’ array, however if there were more records matched than what was returns in the ‘customers’ array, this should indicate the total number of matches. This is used for notifying the end-user to use more search parameters to narrow down search results

Customer Object:

Element Name	Required	Description
id	yes	unique id of subscriber, this is used to get the subscriber’s detailed information. This does not have to be numeric.
status	yes	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), or ‘cancelled’ - account has been shut-off and not intended for re-activation
company_id	no	companyid of subscriber (if applicable)
firstname	yes, if used in search	firstname of subscriber, this or the name property must be included in results
lastname	yes, if used in search	lastname of subscriber
name	yes, if used in search	Name of subscriber. Either this or the first/last name properties must be included in results
username	yes, if used in search	username of subscriber
email	yes, if used in search	email address of subscriber
businessname	yes, if used in search	businessname for account
postalcode	yes, if used in search	postalcode/zipcode for subscriber
address	yes, if used in search	address for subscriber
city	yes, if used in search	city for subscriber

Example Response JSON

An example response for a search on the URL:

https://www.example.com/searchsubscribers?username=test&firstname=&lastname=smith&companyid=1&key=abc123&email=

JSON Response Body:

{'error': null,
 'number_of_results': 1,
 'customers': [{
   'id': 54321,
   'status': 'active',
   'firstname': 'Bob',
   'lastname': 'Smith',
   'email': 'bobsmith@example.com'
 }]
}