Object Lists

The OnTime SOAP and REST API allow for the retrieval of lists of identifiers of certain objects. Is also allows developers to search for particular object identifiers and filter the aforementioned lists based on some criteria. The following objects in the OnTime SOAP and REST API have this functionality.

• Customers
• Invoices
• Locations
• Orders
• Payments
• Users
• User Sessions
• Vehicles
• Zones

Querying and Filtering in the OnTime SOAP API

The OnTime SOAP API contains two functions for each of the aforementioned objects for querying and filtering. These functions are explained as follows.

Simple Filtering in the OnTime SOAP API

The first filtering function simply filters a list of identifiers by a single criterion. For example, the following VB.NET code can be used to retrieve a list of user identifiers who are drivers.

Dim results As List(Of Guid) = Service.GetUserListWhere(ServiceReference.UserColumn.IsDriver, True)

Advanced Filtering Using the Where Function and the Filter Object

The other function for filtering object identifiers makes use of the Filter objects in the OnTime SOAP API. The GetUserList function is one such function. There are three types of filters available in the OnTime SOAP API: FilterExact, FilterContains, and FilterRange.

FilterExact

The FilterExact object has two properties. The Column property is an enumeration value from a column enumeration defined in the OnTime SOAP API, and the Value property is an object to filter by exactly. The following VB.NET code demonstrates the use of the FilterExact object in conjunction with the GetUserList function. This code returns the same result as the previous example that used the GetUserListWhere function.

Dim filter As New ServiceReference.FilterExact
filter.Column = ServiceReference.UserColumn.IsDriver
filter.Value = True
Dim results As List(Of Guid) = Service.GetUserList(New ServiceReference.Filter() { filter })

FilterContains

The FilterContains object has two properties. The Column property is an enumeration value from a column enumeration defined in the OnTime SOAP API, and the Value property is an object to filter by exactly. The following VB.NET code demonstrates the use of the FilterContains object in conjunction with the GetUserList function. This code returns a list of user identifiers whose email address contains the string '@gmail.com.'

Dim filter As New ServiceReference.FilterContains
filter.Column = ServiceReference.UserColumn.Email
filter.Value = "@gmail.com"
Dim results As List(Of Guid) = Service.GetUserList(New ServiceReference.Filter() { filter })

FilterRange

The FilterRange object has five properties. The Column property is an enumeration value from a column enumeration defined in the OnTime SOAP API, the MinValue property is an object representing the minimum value to filter by, the MaxValue property is an object representing the maximum value to filter by, the IncludeMin property is a Boolean value (set to true by default) indicating whether to include the minimum value or not, and the IncludeMax property is a Boolean value (set to true by default) indicating whether to include the maximum value. The following VB.NET code demonstrates the use of the FilterRange object in conjunction with the GetUserList Function. This code returns a list of user identifiers that were hired between the dates of January 1, 2017 and January 1, 2018, and includes users that were hired on January 1, 2017 and January 1, 2018.

Dim filter As New ServiceReference.FilterRange
filter.Column = ServiceReference.UserColumn.HiredDate
filter.MinValue = New DateTime(2017, 1, 1)
filter.MaxValue = New DateTime(2018, 1, 1)
Dim results As List(Of Guid) = Service.GetUserList(New ServiceReference.Filter() { filter })

The FilterRange object is flexible in that only one of the bounds must be defined. For example, the following VB.NET code returns a list of user identifiers that were hired after the date of January 1, 2017.

Dim filter As New ServiceReference.FilterRange
filter.Column = ServiceReference.UserColumn.HiredDate
filter.MinValue = New DateTime(2017, 1, 1)
Dim results As List(Of Guid) = Service.GetUserList(New ServiceReference.Filter() { filter })

Composing Multiple Filters

Filters can be composed in the OnTime SOAP API to allow developers to filter object identifiers based on multiple criteria. The following code demonstrates how to compose filters. The code returns a list of user identifiers who are drivers and were hired after the date of January 1, 2017.

Dim exactFilter As New ServiceReference.FilterExact
exactFilter.Column = ServiceReference.UserColumn.IsDriver
exactFilter.Value = True
Dim rangeFilter As New ServiceReference.FilterRange
rangeFilter.Column = ServiceReference.UserColumn.HiredDate
rangeFilter.MinValue = New DateTime(2017, 1, 1)
Dim results As List(Of Guid) = Service.GetUserList(New ServiceReference.Filter() { exactFilter, rangeFilter })

Query and Filtering in the OnTime REST API

Querying and filtering in the OnTime REST API is done through the URL of certain HTTP GET requests. The following is an example of an HTTP request and response for retrieving a list of user identifiers whose name is John Doe.

GET /api/users?firstName=John&lastName=Doe HTTP/1.1
Host: www.example.com
Authorization: YOUR-API-KEY
Content-Type: application/json
Cache-Control: no-cache

[
    "50b77228-c700-4208-9da6-83504178db7c"
]