Searching & Filtering

The standard ways results in collections can be limited

Predefined searches

Complicated searches with grouped search terms and a rich set of operators can be configured in the main ATS application and used in calls to GET collections by their ID. These are supplied via the saved_search or config_search query parameters (saved_search refers to searches set up by normal users, config_search refers to searches configured generally and available to all users).

GET /api/v1/applications?saved_search=123

GET /api/v1/applications?config_search=123

Predefined selections

The ATS application has a concept called ‘selections’ which are explicit subsets of the resource in question that can be named and manipulated. The selection query parameter can be used in calls to GET collections to only return members of that selection.

GET /api/v1/applications?selection=123

Ad-hoc searching

The search query parameter can be used to search for a specific subset of a collection, this is a URI escaped string representing a search condition in the form of:

search=<key><operator><value>

The key is either a JSON pointer or one of our datapaths. A JSON pointer can be used to address attribute(s) of the resource representation to search on, whereas a ‘datapath’ can be used to refer to any arbitrary value than can be linked to from the resource in question. Although much more flexible than the JSON pointer the disadvantages of datapaths are that they are not as discoverable and may have to include arbitrary IDs.

Multiple instances of the search parameter, including a mixture of JSON pointer and datapath styles can be supplied, these are ANDed together.

In JSON pointer syntax elements of lists can only be addressed with * (any) or our custom syntax <label> available labels are detailed in the response schema.

The value is either a plain string or a comma seperated list of strings enclosed in curly braces. Lists can only be used with the = and != operators and provides IN, NOT IN style semantics.

The operator can be:

  • =, != Exact match, non-match
  • =~, !~ Case insenstive sub string match
  • <, >, >=, <= Order comparisons

Examples

Getting applications:

GET /api/v1/applications?search=...

  • /user/id=123 - Applications with user ID 123
  • application.user=123 - Same as above but with a datapath
  • /user/id={123,456} - Applications with user ID 123 or 124
  • /user/firstname=~bob - The application user’s firstname contains ‘bob’
  • /process_state/state=~interview - The current process state of the application’s title contains ‘interview’

Getting candidates:

GET /api/v1/candidates?search=...

  • /Address/*/AddressLine=~High Street - Candidates with any address that contains ‘High Street’
  • /Email/[personal]/Address=~gmail.com - Candidates with an email address labelled ‘personal’ that contains ‘gmail.com’

Filtering

The filter query parameter can be supplied to filter the collection by a string. Attributes marked ‘filterable’ in the resource description are considered, these are usually all the text and date attributes.

For example: GET /api/v1/users?filter=Oxford will return all candidates with the string ‘Oxford’ in any of the filterable attributes - addresess, education etc.