HRlab API (2.0)

Introduction

This is the documentation for the new version 2 of the HRlab API. It provides guidance for data exchange data between HRlab and external systems.

The documentation is written in OpenAPI format 3.1.0. In addition to standard OpenAPI syntax we use a few vendor extensions.

The API is build following the REST convention. All API-Calls are made under https://app.hrlab.de/external_api/v2. Responses and Requests are in JSON format.

The documentation process on available endpoints is still ongoing. If you need information about an endpoint that is not documented yet, please contact us.

Authentication

The HRlab API v2 allows for only one authentication method, using Application Tokens. The token needs to be included in the header of every request. The Name of the Header needs to be Authorization, while the value of the header is the token itself.

Example:

Authorization: 123456789

To get your Application Token, you need to create an API Application in HRlab. This will generate an Application Token which you can use to authenticate your requests. After generating the Application Token, you need to set the required permissions for the desired endpoints to access the API.

Request Limiting

The amount of requests is limited to 60 requests per minute per default. If you exceed this limit, you will receive a 429 Too Many Requests error. More information about the current limit is send in every response and can be found in the header:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 9
X-RateLimit-Reset: 12
X-RateLimit-Policy: '60;w=60'

If you exceed the limit, the X-RateLimit-Reset header will contain the time in seconds until the limit is reset. The time Window will reset every full minute.

Data Types

Below you can find important data types that can be used in the request and response bodies. Furthermore, there is information about the data types in the documentation of each endpoint.

Responses

Sorting

You can sort the results by every field, that is returned in the first level of the response. We don't support sorting for nested fields.

The sorting order can be ascending or descending. The syntax for sorting is key+ for ascending and key- for descending. You need to send + and - as URL encoded values:

• %2B for +
• %2D for -

For example, this request gets all the users, sorting by last name in ascending order:

GET /external_api/v2/users?sort=last_name%2B

Filtering

The results can be filtered by one or more fields, that are returned in the first level of the response.

We do not support filtering for nested fields.

We use LHS-Bracket syntax for filtering. The syntax is field_name[operator]=value.

You can use the following operators:

• LTE - Lower than equal (<=)
• LT - Lower than (<)
• GTE - Greater than equal (>=)
• GT - Greater than (>)
• NEQ - Not equal (!=)
• EQ - Equal (==)
• CONTAINS - contains; just available for strings
• BETWEEN - between; Just for integers or date(time)s
• NULL - is null or not null

All filters are connected with an "AND". You need to send [ and ] as URL encoded values:

• %5B for [
• %5D for ]

Examples:

# Example GTE: 10 <= price <= 200
GET https://app.hrlab.de/external_api/v2/bonus_targets?target_amount[LTE]=200&target_amount[GTE]=10

# Example NULL: price is null
GET /external_api/v2/bonus_targets?target_amount[NULL]=true

# Example NOT NULL: price is not null
GET /external_api/v2/bonus_targets?target_amount[NULL]=false

# Example CONTAINS: first_name contains "John"
GET /external_api/v2/users?first_name[CONTAINS]=John

# Example BETWEEN: 10 <= target_amount <= 200
GET /external_api/v2/bonus_targets?start_date[BETWEEN][]=21-08-2023&start_date[BETWEEN][]=27-08-2023