Overview

There are several URL parameters available to help you control the data that is returned fromGET 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.

Filter

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 ().

Examples

• 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')

Available operators

Include

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.

Examples

• Retrieve a customer and their system information: GET /user/v1/customers?include=customer_system_information
• Includes can also be strung together to return even more information: GET /user/v1/customers?include=customer_system_information,customer_order_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: GET /user/v1/customers?include=customer_system_information.install_calendar_event

Sort

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.

Examples

• Sort ascending by id: ?sort=id
• Sort descending by id: ?sort=-id

Pagination

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 limit and page URL parameters.

Note: if requests are paginated a links block will be included at the end of the JSON response.

Examples

• Retrieve page 2 of customers: GET /user/v1/customers?limit=100&page=2.

Note: 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.

Wrap up

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:

• GET /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