Multi-Route Filters

Request Filter

Most routes support a universal request filter to control the data that you receive back in the response. Not all routes support all features of the request filter, so in any given route's documentation page, you will see a table like below, indicating what request filter options are honored by that route. Specifying a request filter not honored by that route will not cause an error, but will also have no effect. Additionally, you can specify multiple ID filters if they are supported by the route, and they will all be applied.

Filter Name	Type	Default Value	Description
startDate	DateTime	`endDate` minus the route's maximum search range	Excludes all records that occurred before this date. If omitted, defaults to the route's maximum search range before `endDate`. If the requested range exceeds that maximum, `endDate` is silently clamped rather than rejected. The maximum range varies per route, so see the individual route documentation and the clamping rules.
endDate	DateTime	Current UTC DateTime	Excludes all records that occurred after this date. If omitted, defaults to the current UTC time.
includeDeleted	bool	False	Includes deleted records that are normally excluded from the response.
organizationIds	List[int]	null	Filter results to only the specified Organization or their child records.
accountIds	List[int]	null	Filter results to only the specified Accounts or their child records.
siteIds	List[int]	null	Filter results to only the specified Sites or their child records.
machineIdentifiers	List[string]	null	Filter results to only the specified Machines or their child records. Supports specifying machines by either ID or PROSE.
selectionIds	List[int]	null	Filter results to only the specified Selections or their child records.
productIds	List[int]	null	Filter results to only the specified Products or their child records.

Permissions Filter

All role, role right, and right related routes use the PermissionsFilter for further filtering. Its definition follows.

Filter Name	Type	Definition
roleIdentifiers	List[string]	Filters the results to only roles that have either the specified ID or role name.
rightIds	List[int]	Filters the results to only the specified rights.
roleRightIds	List[int]	Filters the results to only the specified role right IDs.

Templating Filter

All template, template group and template selection related routes use the TemplatingFilter for filtering. Its definition follows.

Filter Name	Type	Definition
templateIds	List[int]	The template IDs you'd like to filter the result set to.
createdBefore	DateTime?	Only return records created before the specified date and time.
createdAfter	DateTime?	Only return records created after the specified date and time.
modelId	int?	Filters the result set to only records attached to machines with this model.
templateGroupIds	List[int]	Filters the result set to only records related to the specified template groups.
templateSelectionIds	List[int]	Filters the result set to only records related to the specified template selections.

Files Filter

The files, file links, and file metadata routes use the FilesFilter for filtering. Its definition follows.

Name	Type	Meaning
fileIds	List[int]	Filter result set to only the files whose IDs are in the list.
fileMetadataIds	List[int]	Filter result set to only the file metadatas whose IDs are in the list.
fileLinkIds	List[int]	Filter result set to only the file links whose IDs are in the list.
linkedRecordIds	List[int]	Filter a file links result set to only links that link to the specified records.
bucketName	string	Optional override. For internal use only.
fileStatuses	List[FileStatus]	Filter result set to only files with the specified statuses. Accepts the enum's string names (e.g. `Available`, `PendingUpload`); the underlying integer values are also accepted.
fileLinkTypes	List[FileLinkType]	Filter result set to only file links that link to the specified record types. Accepts the enum's string names (e.g. `Alert`, `Sale`, `SaleBatch`); the underlying integer values are also accepted.

Alert Filter

The alerts and alert metadata routes takes in an optional object to provide further filtering. Fields and meanings are:

Name	Type	Meaning
alertIds	List[int]	Filter result set to only alerts whose IDs are in the list.
alertMetadataIds	List[int]	Filter result set to only alert metadatas whose IDs are in the list.
alertCodes	List[string]	Filter result set to only alerts whose code is in the list.
isCleared	bool?	Filter result set to only alerts that are/are not already cleared.
isUserClearable	bool?	Filter result set to only alerts that are/are not user clearable.
includeDebugAlerts	DebugInclusivity	Indicates if you want debug alerts included in the result set. Accepts the enum's string names (`Exclude`, `Inclusive`, `Exclusive`); the underlying integer values are also accepted. See below for values and meanings. Defaults to `Exclude` (0).
raisedAtStart	DateTime?	Filter result set to only alerts that were raised after the specified UTC DateTime.
raisedAtEnd	DateTime?	Filter result set to only alerts that were raised before the specified UTC DateTime.
clearedAtStart	DateTime?	Filter result set to only alerts that were cleared after the specified UTC DateTime.
clearedAtEnd	DateTime?	Filter result set to only alerts that were cleared before the specified UTC DateTime.

The log search route uses the LogSearchFilter for further filtering. Its definition follows.

Filter Name	Type	Definition
logTypes	List[string]	Filter result set to only logs whose type is in the list. Omitting this filter returns all log types.

includeDebugAlerts Values

Value	Meaning
0	Do not include debug alerts in the result set.
1	Include debug alerts in the result set.
2	Only return debug alerts.

Transaction Filter

Field Name	Type	Description
transactionIdentifiers	List[string]	A list of transaction identifiers. The format of identifiers may vary. To indicate a batch prepend a `b` to the integer ID.

SessionFilter

Attribute	Type	Description
sessionIds	List[int]	The IDs of the sessions that you want to retrieve.
sessionEventIds	List[int]	The IDs of the session events that you want to retrieve.

Settings Filter

Attribute	Type	Description
includeInactive	bool	Dictates if result set include inactiveSettings. Defaults to false.
groupIds	List[int]	Filters the result set to settings belonging to one of the indicated groups.
settingsIds	List[int]	Filters the result set to only the specified settings.

Rules Filter

Attribute	Type	Description
includeInactive	bool	Dictates if result set include inactive rules. Defaults to false.
groupIds	List[int]	Filters the result set to rules belonging to one of the indicated groups.
ruleIds	List[int]	Filters the result set to only the specified rules.
applyHierarchicalFiltering	bool	Indicates if the result set should be hierarchically filtered. See GET rules for more information.
includeRuleTree	bool	Changes the behavior of filters. Normally specifying multiple filters only returns data that matches all of them. Setting this to true returns all data that matches ANY provided filter.

Credit Filter

Attribute	Type	Description
gatewayIds	List[int]	Filters the result set to items associated with the specified gateways.
chargeKeyIds	List[int]	Filters the result set to items to the specified charge keys.

Terminal Filter

Attribute	Type	Description
terminalIds	List[int]	Filters the result set to the specified payment terminals.

Machine Types Filter

Attribute	Type	Description
machineTypeIds	List[int]	Filters the result set to the specified machine types.

Products Filter

Attribute	Type	Description
isACommonProduct	bool?	Filter to only results that are/are not a common product. Defaults to null.
includeDeleted	bool	Indicates if the result set should include products that have been deleted. Defaults to false.
productVariantIds	List[int]	A list of IDs of product variants to retrieve/delete.