HRMTS provides a set of RESTFul Web Service to retrieve various information through Third Party Systems. The function of this Web Service is restricted to read-only.
Following configuration in the System is required before the Web Service can be used:
HRMTS Support can assist the Customer in this configuration
Successful responses from all Web Service methods follow a common convention. The HTTP status code for all successful responses is 200.
The root element describes the type of data being returned. In the example above, the candidate list is being returned.
The node for execution time indicated the time used on the server to deliver this data. This data is included for the benefit of both Customer and HRMTS. The customer can keep a log of average delivery time for their typical method calls and report in case of inconsistencies. Also, they can see which method calls are expensive so that they can call the methods in a more optimized way. HRMTS can benefit from these values when debugging or extending the Web Service and during releases.
The node for customer repeats the basic customer information that is supplied in the call to Web Service method.
The node for counts provide information on various counts on the data that is delivered. This information is useful in implementing paging support.
Node | Description |
Search Count | Number of elements that match the criteria. May be more than what is delivered in the current call. |
Skip Count | Number of elements that match the criteria and are skipped or jumped. |
Take Count | Number of elements that match the criteria and are included in the results. |
Total Count | Total number of elements available on the server. In the example above, the value indicates 106 candidates in the Customer account. |
The node for sort indicates the sorting criteria used in the results.
Node | Description |
Field | The field on which the results are sorted by. |
Direction | The direction of sort – ascending or descending. |
Failed responses from all Web Service methods follow a common convention. The HTTP status code for all successful responses is according to the error that has occurred, e.g. 500.
The root element describes the transaction status.
Represents the HTTP status code.
Describes the actual error that occurred on the server.
Depending on the query string parameters, the Web Service methods may return one or more data objects. Each data object is divided into two parts. The first part consists of basic properties such as id, name etc., while the second part consists of all other detailed properties.
When more than one data objects are returned by a Web Service method, only the basic properties are included in the results. The detailed properties are not included to make the delivery lightweight. Only when a single data object is returned, then the detailed properties are also included.
All Web Service methods accept query string parameters to know type and amount of data to return. Each method has its dedicated parameters, while following parameters are common for all methods.
Parameter | skip |
---|---|
Description | Send this paging parameter to define how many data objects to skip from the beginning of the list once the search and filter criteria are applied. |
Value type | Integer |
Default value | 0 |
Sample | …/?skip=1 |
Parameter | take |
---|---|
Description | Send this paging parameter to define how many data objects to include in the returned list once the search and filter criteria are applied. Take is limited to 100 in all API methods. |
Value type | Integer |
Default value | 25 |
Sample | .../?take=10 |
Parameter | sortby |
---|---|
Description | Send this parameter to sort the list with a specific property of the data object. Only limited number of properties are supported for sorting. |
Value type | string |
Default value | "Id" |
Sample | .../?sortby=id |
Parameter | sortasc |
---|---|
Description | Send this parameter to sort the list in the ascending order with value defined in “sortby” |
Value type | Boolean |
Default value | True |
Sample | .../?sortasc=1 |
Parameter | uiculture |
---|---|
Description | Send this parameter to get the localized text for the values of dropdown lists, e.g. education etc. The available languages are:
|
Value type | text |
Default value | Default customer language |
Sample | .../?uiculture=en |
Parameter | depid |
---|---|
Description | Send this parameter to filter the list with a single department id. |
Value type | Integer |
Default value | Root department id |
Sample | …/?depid=1 |
Parameter | incsub |
---|---|
Description | Send this parameter to include the sub departments in filtering of data objects. |
Value type | Boolean |
Default value | False |
Sample | .../?incsub=1 |