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.

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.

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.

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.

Date/Time

ISO 8601 date format is used for all date/time fields. All recorded times are saved in UTC format without regard to the time zone. This means that a working time that starts at 08:00:00 GMT+2 will still be saved as 08:00:00 UTC.

Example: 2021-10-13T08:00:00Z

Enum

Enum values are represented as strings or integers. The possible values are listed in the documentation, with the information if a string or integer is required.

Null-values

Null values are represented as null.

Language

The language or nationality is represented as a string in ISO 3166-1 alpha-2 format.

The API uses the following standard HTTP status codes:

• 200 OK - Everything worked as expected.
• 201 Created - The request was successful and a resource was created.
• 204 No Content - The request was successful but there is no content to return.
• 400 Bad Request - The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
• 401 Unauthorized - Authentication credentials were missing or incorrect.
• 402 Payment Required - The request is understood, but it has been refused or access is not allowed. This means basically that you exceeded your request limit.
• 403 Forbidden - The request is understood, but it has been refused or access is not allowed.
• 404 Not Found - The URI requested is invalid or the resource requested, such as a user, does not exist.
• 422 Unprocessable Entity - The request was well-formed but was unable to be followed due to semantic errors.
• 429 Too Many Requests - Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
• 500 Internal Server Error - Something went wrong on our side.

Error responses are returned with a JSON body. The body contains the following fields:

• status - The error code.
• message - A human readable error message.
• detailed_info - Additional information about the error.

Example: { "status": "404", "message": "Not Found", "detailed_info": "Could not find Record with 'id'=100" }

400 Bad Request

  - `invalid request` - The request is invalid.
  - `invalid filter` - The filter is invalid.
  - `invalid sort` - The sort is invalid.

401 Unauthorized

  - `invalid token` - The token is invalid or not present.

402 Payment Required

  - `rate limit exceeded` - You exceeded your request limit.

403 Forbidden

  - `insufficient permissions` - You do not have the required permissions to access this resource.

404 Not Found

  - `not found` - The resource was not found.

422 Unprocessable Entity

  - `invalid data` - The data is invalid.
  - `invalid data type` - The data type is invalid.
  - `invalid enum value` - The enum value is invalid.
  - `invalid date` - The date is invalid.
  - `invalid time` - The time is invalid.
  - `invalid date/time` - The date/time is invalid.

429 Too Many Requests

  - `rate limit exceeded` - You exceeded your request limit.

500 Internal Server Error

  - `internal server error` - Something went wrong on our side.

    # Pagination
    We use `limit` and `offset` for pagination.

By providing a value for limit you can limit the number of records returned. The maximum and default value for limit is 50.

The offset is the number of records to skip. If you do not specify a value for offset, the default value is 0.

Example:

GET /external_api/v2/users?limit=10&offset=20

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

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

Operations for HomeOffices

Operations for Sicknesses

Operations for Travels