Web Services filters

Maximum records parameter

The header parameter x-ftm-max-records prevents queries from running that result in too many records that match the filter criteria that is provided on the service request. If the x-ftm-max-records parameter is not specified, or it is specified with a value of less than 1, the system-defined maximum records value is used. For more information, see the “Web Service Maximum Range Value” property in Control Center.

An HTTP 500 response is returned when the record count in the result set exceeds the maximum allowed value.

Range parameter

Filters

Optional query parameters serve as filter specifications. The general format is parameter_name=~operator~value, where the operator (including the surrounding tilde characters) is an encoded string. This string indicates the type of comparison to do when the value is matched to the database column that corresponds to the parameter_name. If no operator is provided, the default comparison is an exact match. For example, if the query parameter transmission_id=4 is the only query parameter that is submitted for GET transactions, all transactions for transmissions with an ID equal to 4 are returned if possible. All records are returned only if the x-ftm-max-records count is not exceeded and they fit in the paging that is specified in x-ftm-range.

A predicate that is formed for a query parameter and the predicates that are formed for all other query parameters are connected by the AND operator. For example, if business_date=2020-10-30 and batch_id=~range~100-700, only those transactions that match both criteria are returned.

While all query parameters are submitted as strings, the values they represent map to varying data types. For example, transmission_id maps to an underlying numeric value and business_date maps to an underlying date value. The data types that are supported for filtering are string, numeric, local date, and offset date time. Not all operators can be used with all underlying data types.

Query parameters that are defined as arrays behave differently. Each element in an array must contain only a value, an ~operator~ cannot be specified. Comparisons for individual elements are always exact matches. Predicates that are formed from array elements of a specific query parameter are connected with each other in the collection with the OR operator. The series of predicates that are connected by the OR operator for a specific array query parameter is attached with the AND operator to predicates formed for other query parameters.

Consider the following request as an example: /pfs/transactions?business_date=~range~2020-09-07-2020-09-11&schemes=payscheme1&schemes=payscheme2&originator_id=ABC123.