Filtering

Summary

Often only a subset of the results from a Collection Endpoint is required.  Therefore, instead of having to traverse the collection you can tell the API to restrict results based on a set of criteria.

Filtering

In order to apply filtering criteria to an endpoint, you must supply the property name and the value that you wish to filter on. The property names available to filter on are found by checking the format of the HTTP 200 Success response sample found in the reference.

In the case of the Companies endpoint, we see that the response format is as follows meaning that we can filter on any or all of Id, Name or Enabled:

{
  "id": 5,
  "name": "Awesome Inc.",
  "enabled": true
}

To filter an endpoint, we append the property name and required value to the URL when sending a request. So, for example, we could filter for all enabled companies by sending the following request:

curl "https://api.youmanage.co.uk/Companies?Enabled=true"

{
  "id": 5,
  "name": "Awesome Inc.",
  "enabled": true
}

Note that any values used as a filter value need to be URL Encoded to a format that is safe to send in an HTTP request - most modern programming languages should have facilities to do so.

Multiple Filters

If you need to include more than one filter in a request, simply append each filter to the URL as before but separated by an ampersand (&):

curl "https://api.youmanage.co.uk/Companies?Enabled=true&Name=Awesome%20Inc"

{
  "id": 5,
  "name": "Awesome Inc.",
  "enabled": true
}

Filtering Operations

The default operation used when filtering is equality, does the given value exactly match the value of the property. This is usually sufficient, however, in some cases other operations are required and as such the API supports a number of filtering operations.

To apply a filter operation other than equals simply prepend the value used to filter with the operation code. For example if you wanted to return absences that started before a certain date you could issue the following request.

curl "https://api.youmanage.co.uk/Absences?Start=%3C2019-06-01T00%3A00%3A00Z"

[
  {
    "id": 265,
    "status": "Approved",
    "employeeId": 3,
    "employee": "Mary-Jane Parker",
    "type": "Holiday",
    "reason": "Annual Leave",
    "start": "2019-05-02T00:00:00Z",
    "end": "2019-05-03T00:00:00Z",
    "period": {
      "prefered": "Hours",
      "days": 1.00000000,
      "hours": 7.50000000
    }
  }
]

All values must be properly URL encoded as seen in the above filtering example, where the value for Start when decoded would look like <2019-06-01T00:00:00Z.

It can also be useful to search for absences that occurred during a range of time, to do this you can send a request with multiple filters for the same property. For example, if you wanted to search for absences that started during a month then you could send the following request.

curl "https://api.youmanage.co.uk/Absences?Start=%3E2019-06-01T00%3A00%3A00Z&Start=%3C2019-07-01T00%3A00%3A00Z"

[
  {
    "id": 269,
    "status": "Approved",
    "employeeId": 3,
    "employee": "Mary-Jane Parker",
    "type": "Holiday",
    "reason": "Annual Leave",
    "start": "2019-06-23T00:00:00Z",
    "end": "2019-06-25T00:00:00Z",
    "period": {
      "prefered": "Hours",
      "days": 2.00000000,
      "hours": 15.00000000
    }
  }
]

Any number of filters and operations can be applied to a property and each of these conditions must match for a record to be returned. The API does not currently support OR operations when applying filters.

Next up we'll move on to how you can traverse through a collection endpoint and configure how many results are returned in each request in our paging guide.