Applications

The space separated fields included in the returned records. If omitted the default list of fields will be returned.

The number of records to return at once.

The offset into the records to return.

The space separated fields used to sort the collection. Default sort is ascending, prefix with - to sort descending.

A filter to apply to the query. See the supported operators below. For more complex searches, see the related /search/<domain> endpoints, e.g. /search/systems.

Filter structure: The filter syntax follows a consistent pattern of <field>:<operator>:<value> (e.g. department:$eq:Finance)

field = Populate with a valid field from an endpoint response.

operator = Supported operators are:

• $eq - equals (exact match)
• $in - equals (multiple match terms). Separate terms by | character: <field>:$in:<term one>|<term two>
  • any item with <field> that matches ANY of the match terms will be returned
  • to use a literal | character inside a match term, it must be "escaped" using a backslash \ ("\|")
    • for GET endpoints, only ONE backslash is needed: costCenter:$in:Atlanta\|Tampa|Chicago
    • for POST endpoints, TWO backslashes are needed due to the nature of JSON: costCenter:$in:Atlanta\\|Tampa|Chicago
    • resulting match terms: "Atlanta|Tampa", "Chicago"
• $ne - does not equal
• $nin - does not equal (multiple match terms). Separate terms by | character: <field>:$nin:<term one>|<term two>
  • any item with <field> that DOES NOT match ANY of the match terms will be returned
  • refer to above $in documentation on using literal | character in match terms
• $lt - is less than
• $lte - is less than or equal to
• $gt - is greater than
• $gte - is greater than or equal to
• $sw - Finds items where the field value begins with the specified term.

Eventually Consistent Operators = These advanced operators support multiple-term matching and require the x-eventually-consistent API request header to be set as true. Terms within the value must be separated by the | character.

• $sw - Matches any item where the field value begins with any one of the provided terms. E.g <field>:$sw:<term one>|<term two>
• $ew - Matches any item where the field value ends with any one of the provided terms. E.g <field>:$ew:<term one>|<term two>
• $co - Matches any item where the field value contains any one of the provided terms. E.g <field>:$co:<term one>|<term two>
• $nco - Matches any item where the field value does not contain any of the provided terms. E.g <field>:$nco:<term one>|<term two>

Note: v1 operators differ from v2 operators.

Note: For v1 operators, excluding the $ will result in undefined behavior and is not recommended.

value = Populate with the value you want to search for. Case sensitive.

Examples

• GET /users?filter=username:$eq:testuser
• GET /systemusers?filter=department:$in:Finance|IT|Shipping & Receiving - an item with { department: "IT" } will match
• GET /systemusers?filter=department:$in:Finance \| Sales|IT - an item with { department: "Finance | Sales" } will match
• GET /systemusers?filter=department:$ne:Accounting
• GET /systemusers?filter=department:$nin:Finance|IT|Shipping & Receiving - an item with { department: "HR" } will match
• GET /systemusers?filter=password_expiration_date:$lte:2021-10-24
• GET /systems?filter[0]=firstname:$eq:foo&filter[1]=lastname:$eq:bar - this will AND the filters together.
• GET /systems?filter[or][0]=lastname:$eq:foo&filter[or][1]=lastname:$eq:bar - this will OR the filters together.
• GET /systemusers?filter=department:$sw:Shipping - an item with { department: "Shipping & Receiving" } will match
• GET /systemusers?filter=department:$sw:Shipping\|Receiving - an item with { department: "Shipping|Receiving Item" } will match
• GET /systemusers?filter=department:$sw:Shipping|Receiving - an item with { department: "Shipping Item" } will match or an item with { department: "Receiving Item" } will match. Use it with x-eventually-consistent header set to true: