Control data in responses
There are several URL parameters available to help you control the data that is returned from
GET requests to the SecurityTrax API. Using these parameters allow you to make your requests more efficient by reducing the number of requests and eliminating unnecessary data.
To filter your requests you will need to provide the following three components:
- The property or field name to filter
- The operator such as
- The filter value
Note: multiple filters can be grouped together using
- Retrieve a list of leads:
GET /user/v1/customers?filter= record_type = 'lead'
Note: spaces can optionally be placed between the operator to improve readability.
- Retrieve a list of customers and leads created in the month of January 2020:
GET /user/v1/customers?filter=(created_at >= '2020-01-01' AND created_at <= '2020-01-31')
|!=||Not Equal to|
|<=||Less than or Equal to|
|>=||Greater than or Equal to|
|OR||Either value 1 or value 2 are true|
|AND||Both value 1 and value 2 are true|
|’||Used to quote strings|
Often the information you need is in several related entries. Gathering such information would require multiple GET requests. Instead, you can use the
include URL parameter to have the API return related information in a single request. When
include is used the data will be returned at the end of the JSON response in an included block.
- Retrieve a customer and their system information:
- Includes can also be strung together to return even more information:
- Include can also be used to drill through relationships by using dot notation. Retrieve customers and the install calendar event from customer_system_information:
API responses can be sorted by using the
sort URL parameter. The default sort order is ascending but can be changed to descending with a
- before the attribute.
- Sort ascending by id:
- Sort descending by id:
Most endpoints that return a list of entities will be paginated. Without pagination, a simple request could return millions or even billions of hits causing extraneous network traffic. Paging requires an implied ordering. By default this will usually be the item’s unique identifier, but can be other ordered fields such as a created date. By default,
GET requests will be limited to 100 records. If more than 100 records exist, additional pages may be requested by using the
page URL parameters.
Note: if requests are paginated a
links block will be included at the end of the JSON response.
- Retrieve page 2 of customers:
limit=0 will return all records in one request. This can result in a lot of data at once and it is recommended you use this carefully.
The URL parameters can be combined for more powerful requests. Using these parameters allow you to make your requests more efficient by reducing the number of requests and eliminating unnecessary data.
Putting it all together example:
/user/v1/customers?filter=(created_at >= '2020-10-01' AND created_at <= '2020-11-02' AND record_type='customer')&include=customer_order_information.activation_fee,customer_order_information.rep_user,lead_company&limit=200&page=1&sort=fname