Introduction

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.

Requirements

Following configuration in the System is required before the Web Service can be used:

Enable the web service in Customer’s account.
Configure an API key.
Configure IP address filter.
Use HTTPS.

HRMTS Support can assist the Customer in this configuration

Success Response Format

Successful responses from all Web Service methods follow a common convention. The HTTP status code for all successful responses is 200.

Root Element

The root element describes the type of data being returned. In the example above, the candidate list is being returned.

Execution Time

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.

Customer

The node for customer repeats the basic customer information that is supplied in the call to Web Service method.

Counts

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.

Sort

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.

Error Response Format

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.

Root Element

The root element describes the transaction status.

Status Code

Represents the HTTP status code.

Status Description

Describes the actual error that occurred on the server.

Important to Know

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.

Common Query String Parameters

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.

Skip

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

Take

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

Sort By

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. (Id, Created, CreatedBy, LastUpdated, LastUpdatedBy)
Value type	string
Default value	"Id"
Sample	.../?sortby=id

Sort Ascending

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

UI Culture

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: da – Danish de – German en – English es – Spanish et – Estonian fr – French fi – Finnish lt – Lithuanian lv – Latvian nl – Dutch no – Norwegian Bokmål nn-no – Norwegian Nynorsk pl – Polish ru – Russian sv – Swedish
Value type	text
Default value	Default customer language
Sample	.../?uiculture=en

Department Id

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

Include Sub Departments

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