Retrieving and Filtering Lists

 

GET commands follow standard RestFul practices. For convenience some methods include helpers which simplify filtering (individual sections will indicate what helpers are available) 

eg GET: /payments_failed/{ddMMyyyy} 

 

 

List Result Format

List requests return two main properties within the response object – Records and Meta. “Records” is an array of the items in the list and “Meta” contains paging information as well as helper links for you to use.

{
  "Records": [{…},{…},{…}],
  “Meta”:
  {
    "page": 3,
    "recs_per_page": 50,
    "total_recs": 412
  }
}

 

List Parameters (optional)

You can customise the list data returned using the following query parameters. These parameters follow the same rules as any standard HTML query string parameter. The first parameter is separated by ‘?’ and subsequent parameters are separated by ‘&’.

 

Parameter

Description

page={x}

{x} is the zero-based index of the page of records to return. Page indexes greater than last page will return an empty page. Negative page indexes will return an error.

per_page={x}

{x} represents records per page. Maximum value is 1000, default value is 100. Values greater than maximum or negative values will return an error.

sort={x,-y,z}

Allows you to sort lists by a defined set of fields. A minus (-) symbol in front of the field indicates descending order. The full list of sortable fields can be found under the heading for each class. Field names are case insensitive and don’t contain spaces. Invalid field names will return an error.

fields={x,y,z,…}

You can specify a comma-separated list of the field names to include for any list. This helps streamline your data, reduce transfers, and enable easier parsing. The order of these fields is respected in the returned result objects. You can see a full field name listing under the heading for each class. Field names are case insensitive and don’t contain spaces. Invalid field names will return an error.

Include={x,y,z}

Some fields are not included in list results by default. You can add them here if you would like them included. EmbeddedObjects (identifiable in the fields lists with a field name containing a “.”) can have their fields explicitly included by using the full dotted field name for example  include=createdby.firstname”

exclude={x,y,z}

You can specify a comma-separated list of the field names to exclude for any list. This helps streamline your data, reduce transfers, and enable easier parsing. You can see a full field name listing under the heading for each class. Field names are case insensitive and don’t contain spaces. Invalid field names will return an error.

{fieldname}={value}

You can filter on field values using this approach. The full list of filterable fields can be found under the heading of each class. String fields are always partial matches matching on any record the field’s string value containing the value provided. Field names are case insensitive and don’t contain spaces. Invalid field names will return an error. A minimum of 2 characters are required for value.

{fieldname}from={value}

Some filterable fields (typically numeric or date fields) allow a ranged search (identified by RNG in fields list). Appending “from” to the fieldname will allow for a search for all values greater than or equal to the “from” value. Field names are case insensitive and don’t contain spaces. Invalid field names will return an error.

{fieldname}to={value}

Some filterable fields (typically numeric or date fields) allow a ranged search (identified by RNG in fields list). Appending “to” to the fieldname will allow for a search for all values less than or equal to the “to” value. Field names are case insensitive and don’t contain spaces. Invalid field names will return an error.

 

List Examples

Retrieve the 4th page of customers

/customers?page=3

 

Retrieve the 4th page of customers with 500 records per page

/customers?page=3&per_page=500

 

Retrieve the 4th page of customers with 500 records per page, but only Code, Name, BillerCode, and BPAYRef fields

/customers?page=3&per_page=500&fields=code,name,billercode,bpayref

 

 

 

Have more questions? Submit a request

Comments