OData

Open Data Protocol (OData) is an open protocol that allows the querying of REST APIs in a simple and standard way. Find out more at odata.org.

OData is available on all endpoints, but some features may not be available.

Example:

Copy 
curl -G https://api.iris.co.uk/hr/v2/employees \
-d "\$filter=DisplayId eq '1'" \
-H "authorization: Bearer <access token>"

Using OData's $filter with Arrays

In our API, there are some nodes that are an array of data rather than a node or collection of data.

Due to an incompatibility between 3rd party components within the API; you cannot directly use $filter on these arrays. You will need to download the data first and then filter what you need afterwards, there is no workaround for this at the moment.

We are looking at ways to resolve this outside of OData and will keep you informed of any changes we make.

Using OData's $select with Arrays

Much like $filter; you cannot directly use $select on these nodes either, however there is a work around for using the $select which we have provided an example of below.

Example:

Copy 
curl -G https://api.iris.co.uk/hr/v2/employees \
-d "\$count=true&$top=250&$select=id,emails/Value,emails/ownership" \
-H "authorization: Bearer <access token>"

In this example it is selecting the first 250 records in the api selecting only the API ID and the Emails array. If the count value is higher than 250 then you need to make additional calls adding $SKIP to the end of your call as shown in the below example.

Example:

Copy 
curl -G https://api.iris.co.uk/hr/v2/employees \
-d "\$count=true&$top=250&$select=id,emails/Value,emails/ownership&$skip=250" \
-H "authorization: Bearer <access token>"

You would increment the $SKIP value by 250 each call until all records are obtained

The $TOP parameter is required in order to bring back data from all arrays. If this value is not included in your call you will be presented with a 500 Error with the following message: "Received non success response code"

Fields that are arrays by endpoint

/Employee

  • Phones

  • Emails

  • Addresses

/PublicHolidays

  • Days

/WorkingPatterns

  • Days

/WorkingPatternsComponants

  • Days

  • Periods