This article explains how to add query parameters to a request to get a specific set of results.
Pagination
To limit the number of records returned by a GET request, use the following two pagination parameters in the query string.
| pageSize | Number of records to retrieve. Default value is 50. |
| page | Record number to start with. Skip to N + 1 record number for the first returned record. Default value is 0 (starts with the first record, none are skipped). |
For example, to retrieve 20 employee records starting from the 30th one, use the following query parameters:
GET https://corehr-api.hrcloud.com/v1/cloud/xEmployee?pageSize=20&page=30
Limiting fields in a response object
When using the GET method to retrieve entities, you can specify ?select= parameter with one or more field names to limit the response to only those fields. The ID, however, is always returned.
Syntax:
?select=:field_name,:field_name
For example, to fetch only the employee first name, nickname and status in a query, use:
GET https://corehr-api.hrcloud.com/v1/cloud/xEmployee?select=xFirstName,xNickname,xEmploymentStatusLookup
The response body in this case would be something like this.
[
{
"xFirstName": "John",
"xNickname": "Johnny",
"xEmploymentStatusLookup": {
"Id": "a47b8a89e6df13e51938e6d9d3648796",
"xType": "Active",
"xRecordStatus": "Active",
"url": "https://corehr-api.hrcloud.com/v1/cloud/xEmploymentStatus/a47b8a89e6df13e51938e6d9d3648796"
}
},
...
]
Similarly, to fetch the list of department names only, use the following query.
GET https://corehr-api.hrcloud.com/v1/cloud/xDepartment?select=xDepartmentName
Filtering
When retrieving resources, you can use the filter query parameter to limit the records in the response object by applying a condition to one or more fields.
For example, to fetch the employee records whose first name is Fred, use the following.
GET https://corehr-api.hrcloud.com/v1/cloud/xEmployee?filter=xFirst_Name eq 'Fred'
Syntax -
filter=:field_name :operator ':string_to_match'
Returns records where the filter condition specified by the operator is satisfied by the field value.
For example, to retrieve employee records where xCity equals to San Francisco, use the following.
GET https://corehr-api.hrcloud.com/v1/cloud/xEmployee?filter=xCity eq 'San Francisco'
Note that in case of LookUp type of fields, embedded fields can also be used to apply a filter criteria as shown in the example below.
GET https://corehr-api.hrcloud.com/v1/cloud/xEmployee?filter=xPositionLookup.xPositionCode eq '111'
and:
GET https://corehr-api.hrcloud.com/v1/cloud/xEmployee?filter=xLocationLookup.xLocationCode eq 'db
Operators
1. startswith : Returns records where the field value begins with the specified string .
Supported Fields: String, Enum, Lookup-String
Syntax:?filter=startswith:string_to_match, :field_name
Example: Return employees whose first names begin with 'St'.
GET https://corehr-api.hrcloud.com/v1/cloud/xEmployee?filter=xFirstName startswith 'St'
2. contains : Returns records where the specified string exists anywhere in the field value.
Supported Fields: String, Enum, Lookup-String
Syntax:?filter=contains:field_name, ':string_to_match'
Example: Return employee records where city contains the string 'San'.
GET https://corehr-api.hrcloud.com/v1/cloud/xEmployee?filter=xCity contains 'San'
3. endswith : Returns records where the field value ends with the specified string.
Supported Fields: String, Enum, Lookup-String
Syntax:?filter=endswith:field_name, ':string_to_match'
Example: Return only those employee records where the position title ends with 'Lead'.
GET https://corehr-api.hrcloud.com/v1/cloud/xEmployee?filter=xPositionLookup.xPositionTitle endswith 'Lead'
4. doesnotcontain: Returns records where the specified string does not exist in the field value.
Supported Fields: String, Enum, Lookup-String
Syntax:?filter=doesnotcontain:field_name, ':string_to_match'
Example: Return employee records who are not 'Managers'.
GET https://corehr-api.hrcloud.com/v1/cloud/xEmployee?filter=xdesignation doesnotcontain 'Manager'
5. eq : Returns records where the field value is equal to the given value.
Supported Fields: String, Enum, Lookup-String, Number, Date, Boolean
Syntax:
?filter=:field_name eq :value
Example: Return only those employee records whose start date is '2017-01-27T00:00:00'.
GET https://corehr-api.hrcloud.com/v1/cloud/xEmployee?filter=xStartDate eq '2017-01-27T00:00:00'
6. neq operator: Returns records where the field value is not equal to the given value.
Supported field types : String, Enum, Lookup-String, Number, Date, Boolean
Syntax:
?filter=:field_name neq :value
Example: Return employees whose department is not 'HR'.
GET https://corehr-api.hrcloud.com/v1/cloud/xEmployee?filter=xDepartment neq 'HR'
7. gt : Returns records where the field value is greater than the specified value.
Supported Field Types: Number, Date
Syntax:
?filter=:field_name gt :value
Example: Return employees whose experience level is greater than 5 years.
GET https://corehr-api.hrcloud.com/v1/cloud/xEmployee?filter=xExperience gt 5
8. gte : Returns records where the field value is greater than or equal to the specified value.
Supported Field Types: Number, Date
Syntax:
?filter=:field_name gte :value
Example: Return employees whose experience level is greater than or equal to 5 years.
GET https://corehr-api.hrcloud.com/v1/cloud/xEmployee?filter=xExperience gte 5
Example: Return employees that had an update at or after '2020-11-12T02:33:35'
GET https://corehr-api.qa.hrcloud.net/v1/cloud/xEmployee?filter=xUpdatedOn gte '2020-11-12T02:33:35'
9. lt: Returns records where the field value is lesser than the specified value.
Supported Field Types: Number, Date
Syntax:
?filter=:field_name lt :value
Example: Return employees whose experience level is lesser than 5 years.
GET https://corehr-api.hrcloud.com/v1/cloud/xEmployee?filter=xExperience lt 5
10. lte: Returns records where the field value is lesser than or equal to the specified value.
Supported Field Types: Number, Date
Syntax:
?filter=:field_name lte :value
Example: Return employees whose experience level is lesser than or equal to 5 years.
GET https://corehr-api.hrcloud.com/v1/cloud/xEmployee?filter=xExperience lte 5
Compound Operators
You can use one or more of the above listed operators together to get a specific set of records.
For example: Return employees from HR department who have an experience of 5 or more years.
GET v1/Cloud/xEmployee?filter=xWorkExperiencePrior.Year gte 5 and xDepartmentLookup.xDepartmentName eq 'HR'
The following table summarizes the operator supported for different field types.
Points to note
1. String and Date values should be specified in single quotes.
2. For encrypted fields, only eq and neq operators are supported.
Sorting
You can sort the records returned in a response in either ascending or descending order.
Syntax:
&sort=:field_name asc|desc
For example: Returns the list of departments in the company sorted in ascending order of the value of the field xDepartmentName.
GET https://corehr-api.hrcloud.com/v1/cloud/xDepartment?sort=xDepartmentName asc
Multiple Query parameters
You can add multiple query parameters in a query to get a specific set of records.
For example, the following request returns only those department records where xDepartmentName contains 'Finance', and then sorts the results based on ascending values of xDepartmentName.
GET http://corehr-api.hrcloud.com/v1/cloud/xDepartment?filter=xDepartmentName contains 'A' &sort=xDepartmentName asc
You can also add pagination options to this, for example:
GET http://corehr-api.hrcloud.com/v1/cloud/xDepartment?filter=xDepartmentName contains 'Finance' &sort=xDepartmentName asc &page = 1 &pageSize=10