Query Customization
Some API request queries can be customized to obtain results that better fit the client's needs. This can be done using different options which are detailed below.
filter
The filter parameter is used to filter the results according to the used filter keys such as:
- vacancyStatus
- clientVacancyStatus
- publicationMedia
- date
- updateDate
- vacancyRequestStatus
- applicantCreationMode
QueryString syntax
In order to apply a filter on a operation, the request has to the following syntax in the QueryString:
/{endpoint}?filter=filter_key::value1
For multiple filters, we use the | character to separate them:
/{endpoint}?filter=filter_key_1::value1|filter_key_2::value2
For multiple values, we use the , character to separate them:
http://[site-url]/api/v{number}/{endpoint}?filter=filter_key::value1,value2
Filter values can be of these types:
- string
- date (the ISO 8601 standard must be respected, for example: "2019-01-30")
Operators can also be applied to the filters. The list of operators includes the following:
::(equal):gt:(greater than):ge:(greater or equal):lt:(lower than):le:(less or equal)
As an example, /vacancies?filter=vacancyStatus::published would return the vacancies whose publication status is published.
You can also combine filters using the | operator (e.g. ?filter=vacancyStatus::published|clientVacancyStatus::_TS_CO_OfferStatus_Diffuse).
For more available filter keys see the table below.
The values that can be used for the filters can be found in the libraries. For example, for publicationMedia, the values can be retrieved via the endpoint /api/v1/referentials/publicationmedia.
Note: Offer references may be generated by the Recruiting system or entered by a user and so there is few restriction on characters that could be used. Several characters may cause issues when used in url so we need to encode references with this procedure. Url encode the reference Search and replace % by !.
For example:
2019-Manager H/F -> 2019-Manager%20H%2FF -> 2019-Manager!20H!2FF
q
This is used to find an item via its reference or title (e.g. /vacancies?q=test would return the vacancies that include the word "test" in their title).
offset
The offset refers to the index from which the results will start. For example, ?offset=100 would return the results starting from the item with index 100.
limit
This refers to the number of items returned. For example, ?offset=0&limit=20 will return the 20 first items.
Filter keys and availability
In the table below we list all the filters available for the APIs concerning vacancies, vacancy requests, vacancy request validations and candidates:
| Filter keys: | vacancy | vacancy request | vacancy request validation | candidate |
|---|---|---|---|---|
| id | x | yes (vacancy request reference) | yes (vacancy request reference) | yes (candidate client code) |
| x | x | x | yes | |
| applicantCreationMode | yes | x | x | yes |
| chronoNumber | yes | yes | x | yes |
| contactquery | x | x | x | yes |
| keyword | yes (title and reference) | yes (title and reference) | x | x |
| q | yes (title and reference) | yes (title) | yes (title and reference) | x |
| updateDate | yes | yes | x | yes |
| publicationMedia | yes | x | x | x |
| publishedOnTheMedia | yes | x | x | x |
| reference | yes | x | x | x |
| referenceQuery | yes | x | x | x |
| clientVacancyStatus | yes | x | x | x |
| vacancyStatus | yes | x | x | x |
| clientVacancyRequestStatus | x | yes | x | x |
| vacancyRequestStatus | x | yes | x | x |
| approvalRequestStatus | x | x | yes | x |
| publishedOn | yes | x | x | x |
Some more examples of queries:
?filter=updateDate:gt:2015-03-16&limit=100?filter=publishedOnTheMedia::_TS_CO_PublicationSupport_Internet&limit=100/vacancies?filter=vacancyStatus::Published|publishedOnTheMedia::_TS_CO_PublicationSupport_Internet|updateDate:gt:2023-06-01T00:00:00.000Z/candidates?filter=updateDate:gt:2022-01-10T14:42:05Z|chronoNumber:gt:15|id::ID1,ID2/vacancyrequests?filter=clientVacancyRequestStatus::_TS_CO_PreliminaryJobRequestStatus_Valide|keyword::test