Timebutler API documentation

The Timebutler RESTful API can be used to automatically request data and process the data with other software.

Requesting the API

The API must be requested using a HTTP POST request. The URL for all requests is:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/[...]

The [...] needs to be replaced by the desired API action code. Valid action codes can be found in this documentation below.

For instance the URL could be like this:

Example:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/absences

Authentication

For authentication and authorization purposes, every API request needs to provide the personal API token as a HTTP post parameter:

Name of the parameter Value
auth Your personal API token (retrieve API token )

Two API tokens

There are two API tokens with different access rights:

  • one API token allows to request the personnel files and salary data
  • one API token allows to request the other data

If you want to request one of the following endpoints please use the API token for the personnel files and salary data:

salariespersonnelfiles

If you want to request any other endpoint please use the other API token.

HTTP response codes

Any response will have a HTTP response code, as follows:

Code Name Description
200 OK All good, response contains requested data.
400 Bad request The request was invalid, e.g. the action code does not exist or is invalid
401 Unauthorized Authentication information missing or invalid or API access has been deactivated by user
404 Not found Invalid URL, Version in request URL not supported, malformed URL
405 Method not allowed Invalid HTTP method for the API URL
413 Request Entity Too Large The number of bytes of the uploaded data is larger than the allowed amount (3 MB).
500 Internal server error Internal server error, please retry later

Action codes - Overview

The request URL must contain the action code which will determine the kind of action or information you want to execute or request. Valid action codes are:

API action code Description and URL
absences Retrieve absence entries
Returns a list of all absence entries of all users of a certain year.
https://personalmanagement.ulb.tu-darmstadt.de/api/v1/absences
useraccount Edit user accounts
Modify a user account.
https://personalmanagement.ulb.tu-darmstadt.de/api/v1/useraccount
managerassignment Change the manager assigment
Change the assignment of users to managers
https://personalmanagement.ulb.tu-darmstadt.de/api/v1/managerassignment
users Retrieve user data
Returns a list of all users.
https://personalmanagement.ulb.tu-darmstadt.de/api/v1/users
holidayentitlement Retrieve holiday entitlement data
Returns a list of all users' holiday entitlement data.
https://personalmanagement.ulb.tu-darmstadt.de/api/v1/holidayentitlement
setholidayentitlement Change the holiday entitlement values
Change the holiday entitlement values for an employee
https://personalmanagement.ulb.tu-darmstadt.de/api/v1/setholidayentitlement
workdays Retrieve user workdays data
Returns a list of all workdays of all users.
https://personalmanagement.ulb.tu-darmstadt.de/api/v1/workdays
setworkdays Change the work days of a user
change the work days of a user
https://personalmanagement.ulb.tu-darmstadt.de/api/v1/setworkdays
holidaysets Retrieve holiday sets
Returns a list of all holiday sets
https://personalmanagement.ulb.tu-darmstadt.de/api/v1/holidaysets
worktime Retrieve working time entries
Returns a list of working time entries.
https://personalmanagement.ulb.tu-darmstadt.de/api/v1/worktime
projects Retrieve a list of all projects
Returns a list of all projects (from the work time configuration).
https://personalmanagement.ulb.tu-darmstadt.de/api/v1/projects
projectsimport Create, update or delete projects
Offers commans to create, change or delete projects from the project list.
https://personalmanagement.ulb.tu-darmstadt.de/api/v1/projectsimport
services Retrieve a list of all services
Returns a list of all services (from the work time configuration).
https://personalmanagement.ulb.tu-darmstadt.de/api/v1/services
holidays List of the users' holidays
Returns a list of one or all users's bank holidays for a certain year.
https://personalmanagement.ulb.tu-darmstadt.de/api/v1/holidays
worktimeaccountinperiod Work time accounts - Working time in period
Returns the data from the work time accounts view 'Working time in period'
https://personalmanagement.ulb.tu-darmstadt.de/api/v1/worktimeaccountinperiod
worktimeaccountbalance Work time accounts - Overtime balance
Returns the data from the work time accounts view 'Overtime balance'
https://personalmanagement.ulb.tu-darmstadt.de/api/v1/worktimeaccountbalance
timeclock Virtual time clock
Offers commands for starting, pausing and stopping the virtual time clock.
https://personalmanagement.ulb.tu-darmstadt.de/api/v1/timeclock
timeimportbyevents Import work time entries
Offers commands to import time entries that have been generated by third party time tracking terminals. The time clock events can be imported (start/stop/pause/resume).
https://personalmanagement.ulb.tu-darmstadt.de/api/v1/timeimportbyevents
personnelfiles Request personnel file data
Returns the personnel file data of one or all users.
https://personalmanagement.ulb.tu-darmstadt.de/api/v1/personnelfiles
salaries Request salary data
Returns the salary data of one or all users.
https://personalmanagement.ulb.tu-darmstadt.de/api/v1/salaries

Action code absences

This action will deliver a list of all absence entries of all users of a certain year. If you do not pass the year as parameter, the absences of the current year will be returned.

Request URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/absences

Request parameters

The following parameters can be passed as HTTP post parameters in the request:

Name of the parameter Mandatory Value
year no Year, 4-digits. For instance: 2024. If the year is invalid or not provided, the current year will be used.

Response data

The response will contain the requested data, encoded in UTF-8. The data will be returned as CSV (comma separated value). The first line will contain the column titles, subsequent lines will contain the information of one absence entry, separated by semicolons.

The following columns will be returned:

  • ID
  • From
  • To
  • Half a day
  • Morning
  • User ID
  • Employee number
  • Type
  • Extra vacation day
  • State
  • Substitute state
  • Workdays
  • Hours
  • Medical certificate (sick leave only)
  • Comments
  • User ID of the substitute
  • Columns for the additional entry fields, optional (details see below)

The column "Type" contains the name of the absence type. In order to view the list of absence types, please login as an administrator, then click on the left bottom on "Settings", then below on "More settings", then on the right on "Absence types".

The column "State" may contain the following values:

  • Approved
  • Done
  • In process
  • Rejected
  • Submitted

The column "Substitute state" may contain the following values:

  • Approval pending
  • Approved
  • Automatically approved
  • Denied
  • No approval required

Additional entry fields

For every absence type additional entry fields can be configured. For instance for the absence type 'Business trip' the additional entry fields 'Destination' (text), 'Distance in km' (integer) and 'Day of application' (date) could be configured.

The response data will then contain additional columns: for every absence type there will be a column 'Additional entry fields for <absence type>' followed by one column for every additional entry field.

Example:

If the additional entry fields "Destination" and "Distance" have been configured for the absence type "Business trip" and the additional entry fields "Course name" and "Course fee" have been configured for the absence type "Training", then the following columns will be returned:

The default response data columns as described above (see here), then the folowing columns:

  • Additional entry fields for 'Business trip'
  • Destination
  • Distance
  • Additional entry fields for 'Training'
  • Course name
  • Course fee

Action useraccount

This action can be used to create, change, lock, unlock and delete user accounts.

Request URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/useraccount

Request parameters

The following parameters can be passed as HTTP post parameters in the request:

Name of the parameter Mandatory
for user account
creation		 Mandatory
for user account
changes and locking and deletion		 Mandatory
for change of
email address		 Value
command yes yes yes
The command you want to execute. Possible commands are:

create update modifyemail unlock lock delete

Show details

email yes yes:
email or employeenumber or userid		 yes:
email or employeenumber or userid		 The email address of the user account that shall be created or changed.
employeenumber optional yes:
email or employeenumber or userid		 yes:
email or employeenumber or userid		 Die Mitarbeiter-Nummer des Nutzerkontos, das geändert werden soll.
userid no:
needs to be empty or not be part of the request		 yes:
email or employeenumber or userid		 yes:
email or employeenumber or userid

The userid of the user account that shall be changed.

You can obtain the list of userids by calling the API action users (see here). The userid values never change, so that you need to call the users action only once and save the list of userids in your system.
first_name yes no no The first name of the user, max. 50 characters
lastname yes no no The given name of the user, max. 50 characters
title no no no The title of the user, max. 50 characters
new_email no no yes The new email address for the user account. This parameter is obligarory if you use the command modifyemail only.
gender yes no no
Value of the parameter Meaning
0 Ms
1 Mr
2 Other
employeenumber_new Nein Nein Nein

The employee number for the user account, max. 20 characters.

Hint:
The input employeenumber (see above) is used to identify the user account that needs to be changed. In order to be able to change the current employee number, you can can provide the new value in the field employeenumber_new.
location no no no The branch office for the user account, max. 50 characters
unit no no no The unit for the user account, max. 50 characters
phone no no no The user's phone number, max. 50 characters
mobile_phone no no no The user's mobile phone number, max. 50 characters
cost_unit no no no The user's cost unit, max. 20 characters
additional_info no no no Additional information for the user or user account, max. 500 characters
date_of_birth no no no Date of birth for the user in the format yyyy-mm-dd (for instance 1988-06-26)
date_of_entry no no no Date of entry into the company of the user in the format yyyy-mm-dd (for instance 2020-03-15)
date_of_separation no no no Date of separation from the company of the user in the format yyyy-mm-dd (for instance 2025-12-31)
timetrack_startdate no no no Start date for the work time tracking in the format yyyy-mm-dd (for instance 2025-03-15).
If the time tracking feature is not active then this date will have no impact.
If this date is not set, then the default work time tracking start date will be applied for the user.
Exception: if a date of entry into the company is set and no work time tracking start date, then the date of entry date will be applied.
timetrack_earliest_time no no no Earliest possible start hour for the time tracking in the format hh:mm (for instance 07:00 in order to set the earliest start hour to 7 am in the morning). The time may be provided in 5 minute intervals: 00:05, 00:10, 00:15, ... 23:55.
If the time tracking feature is not active then this parameter will have no impact.
If this parameter is not set, then the default earliest start hour will be applied for the user.
locale yes no no

Locale (language and country) of the user. The locale will be used in order to determine the language of the emails that Timebutler sends to the user.

Parameter value Meaning
de_DEGerman
en_UKEnglish
en_USEnglish (US)
user_type yes yes (only for update) no

The user type for the user account.

Parameter value Meaning
employee Employee use account
manager Manager user account
admin Administrator user account

Response data

The response will contain one of the following values:

Show response values >

Action managerassignment

This action can be used to change the assigment of users to managers.

Request URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/managerassignment

Reques parameters

The following parameters can be passed as HTTP post parameters in the request:

Parameter Obligatory Value
email yes:
email or employeenumber or userid		 The email address of the user account, whose manager assignment you want to change.
employeenumber yes:
email or employeenumber or userid		 The employee number of the user account, whose manager assignment you want to change.
userid yes:
email or employeenumber or userid		 The user id of the user account, whose manager assignment you want to change.

You can obtain the list of userids by calling the API action users (see here). The userid values never change, so that you need to call the users action only once and save the list of userids in your system.
manager1 yes The userid of the manager user account, who shall be assigned as the first manager.
manager2 no The userid of the manager user account, who shall be assigned as the second manager.
manager3 no The userid of the manager user account, who shall be assigned as the third manager.
... ... ...
manager10 no The userid of the manager user account, who shall be assigned as the 10. manager.

Response data

The response will contain one of the following values:

Show response values >

Action code users

This action will return the user data.

Request URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/users

Request parameters

No additional request parameters are required or available.

Response data

The response will contain the requested data, encoded in UTF-8. The data will be returned as CSV (comma separated value). The first line will contain the column titles, subsequent lines will contain the information of one user, separated by semicolons.

The following columns will be returned:

  • User ID
  • Last name
  • First name
  • Employee number
  • E-mail address
  • Phone
  • Mobile phone
  • Cost center
  • Branch office
  • Department
  • User type
  • Language
  • User ID list of the user's manager (comma separated list, in case more than one user ID exists)
  • User account locked
  • Additional Information
  • Date of entry (dd/mm/yyyy)
  • Date of separation from company (dd/mm/yyyy)
  • Day of birth (dd/mm/yyyy)

The column "User type" may contain the following values:

  • Employee
  • Manager
  • Admin

Action code holidayentitlement

This action will return the users' holiday entitlement data.

Request URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/holidayentitlement

Request parameters

The following parameter can be passed as HTTP post parameter in the request:

Name of the parameter Mandatory Value
year no Year, 4-digits. For instance: 2024. If the year is invalid or not provided, the current year will be used.

Response data

The response will contain the requested data, encoded in UTF-8. The data will be returned as CSV (comma separated value). The first line will contain the column titles, subsequent lines will contain the information of one user, separated by semicolons.

The following columns will be returned:

  • User ID
  • Vacation contingent
  • Remaining vacation
  • Extra vacation days
  • Additional vacation for severely challenged persons
  • Expired vacation
  • Paid out vacation
  • Further vacation contingent

Action setholidayentitlement

This action can be used to change the holiday entitlement values for an employee.

Request URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/setholidayentitlement

Request parameters

The following parameter can be passed as HTTP post parameter in the request:

Parameter Obligatory Value
email yes:
email or employeenumber or userid		 The email address of the user account, whose holiday entitlement shall be changed.
employeenumber yes:
email or employeenumber or userid		 The employee number of the user account, whose holiday entitlement shall be changed.
userid yes:
email or employeenumber or userid

The user id of the user account, whose holiday entitlement shall be changed.

You can obtain the list of userids by calling the API action users (see here). The userid values never change, so that you need to call the users action only once and save the list of userids in your system.
year yes The year for which the holiday entitlement shall be changed.
holiday_entitlement no Number of days for the holiday entitlement / vacation contingent (in the format nn.n, for instance 25.5)
remaining_leave no Number of days for the remaining vacation from the previous year (in the format nn.n, may be negative, for instance -3.5)
special_leave no Number of days for the extra vacation days / special leave (in the format nn.n, for instance 2.5)
severely_challenged_persons_leave no Number of days for the additional vacation days for severely challenged persons (in the format nn.n, for instance 6.5)
other_leave no Number of days for the additional vacation days for the further vacation contingent (in the format nn.n, for instance 1.5). An admin can activate this further vacation contingent and set a label for the type of contingent.
expired_leave no Number of days for the expired vacation (in the format nn.n, for instance 2.5)
paid_out_leave no Number of days for the for the paid out vacation (in the format nn.n, for instance 8.5)
five_day_week_entitlement no

Number of days the employee had if he worked 5 week-days (in the format nn.n, for instance 8.5, no negative numbers allowed).

This value is used to calculate the new vacation entitlement when there is a change in the entry date, exit date, or the number of weekly working days (only when the change is made by a user, not through the API).

There is only one value that is valid for all years. For technical reasons, a valid value for the year parameter still needs to be passed in this API call.

Response data

The response will contain one of the following values:

Show response values >

Action code workdays

This action will return all working days for all users.

Request URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/workdays

Request parameters

No additional request parameters are required or available.

Response data

The response will contain the requested data, encoded in UTF-8. The data will be returned as CSV (comma separated value). The first line will contain the column titles, subsequent lines will contain the working days information of one user, separated by semicolons.

The following columns will be returned:

  • User ID
  • Valid from (dd/mm/yyyy)
  • Monday working time in minutes
  • Tuesday working time in minutes
  • Wednesday working time in minutes
  • Thursday working time in minutes
  • Friday working time in minutes
  • Saturday working time in minutes
  • Sunday working time in minutes
  • ID of the holiday set

Action setworkdays

This action can be called to change the work days, holidays and planned working time for a user.

Request URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/setworkdays

Request parameters

The following parameters can be passed as HTTP post parameters in the request:


Parameter Obligatory Value
email yes:
email or employeenumber or userid		 The email address of the user account that you want to change.
employeenumber yes:
email or employeenumber or userid		 The employee number of the user account that you want to change.
userid yes:
email or employeenumber or userid

The user id of the user account that you want to change.

You can obtain the list of userids by calling the API action users (see here). The userid values never change, so that you need to call the users action only once and save the list of userids in your system.
group_NN_valid_from1) yes

Start date for the following settings, in the format yyyy-mm-dd (for instance 2025-05-01).

The first parameter group_1_valid_from always needs to have the value 0 (=valid from the beginning). The next values group_2_valid_from, group_3_valid_from, etc. need to contain dates that are after the previous dates (for instance 2025-05-01, then 2025-11-15, etc.).

The date values for the beginning of the next period automatically are the end dates for the previous period. Example: the parameter group_2_valid_from = 2025-05-01 means, that the second period starts on 2025-05-01 and automatically implies that the previous period ends on 2025-04-30.
group_NN_working_time_mo1) yes Planned working time in minutes for Mondays (0=not a working day)
group_NN_working_time_tu1) yes Planned working time in minutes for Tuesdays (0=not a working day)
group_NN_working_time_we1) yes Planned working time in minutes for Wednesdays (0=not a working day)
group_NN_working_time_th1) yes Planned working time in minutes for Thursdays (0=not a working day)
group_NN_working_time_fr1) yes Planned working time in minutes for Fridays (0=not a working day)
group_NN_working_time_sa1) yes Planned working time in minutes for Saturdays (0=not a working day)
group_NN_working_time_su1) yes Planned working time in minutes for Sundays (0=not a working day)
group_NN_holiday_set_id1) yes The id of the holiday set that shall be applied for the given period. You can obtain the list of holiday sets by calling the API action holidaysets (see here).
group_NN_overtime_transfer_type1) no
Setting for the calculation of the number of hours not to transfer to the next month. The following values are possible:
Parameter / Meaning
transfer_all (default value)
Always transfer all overtime hours to the next month.
transfer_none
Do not transfer any overtime hours or negative overtime to the next month (the overtime balance will always be 0 h).
transfer_over_limit_only
The number of overtime hours to not transfer can be set with the parameter group_NN_overtime_limit_mins.
transfer_until_limit_only
The maximum number of overtime hours to transfer can be set with the parameter group_NN_overtime_limit_mins.
max_value_start_of_month
The number of overtime hours that may not be exceeded can be set with the parameter group_NN_overtime_limit_mins.
group_NN_overtime_limit_mins1) Only if group_NN_overtime_transfer_type has one of the following values:
transfer_over_limit_only
transfer_until_limit_only
max_value_start_of_month		 The overtime transfer limit according to the trasnfer type, in minutes (for instance 120 = 2 hours).
If this value is provided, it must be larger than 0.
group_NN_round_down_mins1) no

If the work time entry is this number of minutes longer than the planned working time, then round down the work time entry to the planned working time.

Value 0 or parameter not provided: no rounding.
group_NN_round_up_mins1) no

If the work time entry is this number of minutes shorter than the planned working time, then round up the work time entry to the planned working time.

Value 0 or parameter not provided: no rounding.
group_NN_setup_time_mins1) no

If the value is negative: for every calendar day with a work time entry the given number of setup time minutes will be deducted.

If the value is negative: for every calendar day with a work time entry the given number of setup time minutes will be increased.

Value 0 or parameter not provided: no rounding.

1) Information about the parameters group_NN_..

The NN in the parameter names group_NN_.. must be replaced by a number 1 - 99. With the numbers up to 99 periods can be configured. The number identifies the period, so that all parameters that start with the same number (for instance group_1_..) belong to the group of parameters for one period.

You may provide the parameters for up to 99 periods (group_1_... to group_99_...).

Show detailed examples >

Response data

The response will contain one of the following values:

Show response values >

Action code holidaysets

This action will return a list of all holiday sets.

Request URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/holidaysets

Request parameters

No additional request parameters are required or available.

Response data

The response will contain the requested data, encoded in UTF-8. The data will be returned as CSV (comma separated value). The first line will contain the column titles, subsequent lines will contain the information of one holiday set, separated by semicolons.

The following columns will be returned:

  • ID of the holiday set
  • Name of the holiday set

Action code worktime

This action will return all working time entries for a specific month.

Request URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/worktime

Request parameters

The following parameters can be passed as HTTP post parameters in the request:

Name of the parameter Mandatory Value
year no Year, 4-digits. For instance: 2024. If the year is invalid or not provided, the current year will be used.
month no Month from 1 to 12, for instance 2 for February. If the month is invalid or not provided, the current month will be used.

Response data

The response will contain the requested data, encoded in UTF-8. The data will be returned as CSV (comma separated value). The first line will contain the column titles, subsequent lines will contain the workingtime entries, separated by semicolons.

The following columns will be returned:

  • ID of the work time entry
  • User ID
  • Employee number
  • Date (dd/mm/yyyy)
  • Start time (hh:mm)
  • End time (hh:mm)
  • Working time in seconds
  • Pause in seconds
  • State
  • ID of the project
  • ID of the service
  • Comments
  • Auto stopped

The column "State" may contain the following values:

  • Done
  • Requested
  • Accepted
  • Rejected
  • In process

Action code projects

This action will return a list of all projects (from the work time configuration).

Request URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/projects

Request parameters

No additional request parameters are required or available.

Response data

The response will contain the requested data, encoded in UTF-8. The data will be returned as CSV (comma separated value). The first line will contain the column titles, subsequent lines will contain the working days information of one user, separated by semicolons.

The following columns will be returned:

  • ID of the project
  • Name
  • State
  • Budget in hours
  • Comments
  • Creation date

The column "State" may contain the following values:

  • Active
  • Inactive

Action projectsimport

Offers commans to create, change or delete projects from the project list.

Request URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/projectsimport

Request parameters

The following parameter need to be passed as HTTP post parameter in the request:

Name of the parameter Type Value
csvdatafile File

The file with the CSV data to import. For more details, see below.

Format of the CSV file

The CSV file contains the project data. Each line in the CSV file contains one command and one set of project data. The CSV may not contain headers. All lines will be parsed and processed. The delimiter is the semicolon (;).

Each line of the CSV file must contain the following data:

Column / Value Description Format / Example

First column

One of the following commands:
CREATE
UPDATE
DELETE

The command determines which action shall be taken:

CREATE
Create and save a new project.

UPDATE
Change existing project: the CSV data line must contain the porject id (see description for the next column). If a project exists that has the provided ID, then the project values will be changed. If no corresponding project exists, an error will be returned.

DELETE
Delete existing project: the CSV data line must contain the porject id (see description for the next column). If a project exists that has the provided ID, then the project will be deleted (unless an existing working time entry is assigned to the project). If no corresponding project exists, no action will be taken and no error will be returned.

On of the 3 commands.

Examples:
CREATE
DELETE

Second column

ID of the project

The ID of the project which shall be updated or deleted. The ID must be provided except in case of the command CREATE (in this case the ID does not need to be provided but if it has been provided, it will be ignored).

The list of IDs can be retrieved by calling the action projects.

The ID of the project

Examples:
4711
2367

Third column

Name of the project

The name of the project. No value needs to be provided for the command DELETE.

The name may consist of a maximum number of 150 characters. It may not contain carriage returns, line feeds or semicolons.

The name of the project, alphanumeric

Examples:
Pegasus
Zeus II

Fourth column

Project active?
true
false

The project can be set to active (new work time entries for this project) or inactive (new work time entries for this not project).

One of the following two values:
true
false

Fifth column

Project budget in full hours

The budget for the project in hours. The value may be provided but is not required. If provided, it must be an integer larger or equal 0.

The project budget in hours

Examples:
32
1200

Sixth column

Required to select a service?
true
false

When a user assigns a work time entry to this project, he may have to also select a service or no.

One of the following two values:
true
false

Seventh column

Comment

A comment for the project. The comment will be shown to admin users in the edit form for the project list only, not to the employees.

It is not necessary to provide a comment. If provided, a maximum of 200 letters are allowed. The value may not contain carriage returns, line feeds or semicolons.

A comment for the project

Example:
The most important project next year.

Requirements and conditions for the CSV file

CSV file example

Create a project 'Pegasus IV', change the project with the project ID 4711 and delete the project with the project ID 2367:

CREATE;;Pegasus IV;true;48;false;The smallest project in 2025
UPDATE;4711;Zeus;true;;true;
DELETE;2367;;;;;

Response data

The response will contain data as CSV, encoded in UTF-8.

If the input data is missing or could not be read, then the reponse will contain only one line with one error code, for instance CSV_FILE_MISSING_OR_INVALID or CSV_FILE_TOO_LARGE.

If the input data can be processed, then the response will contain one line for each input line.

If the input line has been processed successfully:

line #n: OK;[PROJECT-ID]

If the input line could not be processed:

line #n: [ERRORCODE]

For instance, if CSV data with 5 input lines is uploaded, the response could be the following:

line #1: OK;4711
line #2: OK;815
line #3: LINE_NOT_READABLE
line #4: OK;5838
line #5: PROJECT_ID_UNKNOWN

Error codes

List of possible error codes:

  • INTERNAL_ERROR
  • CSV_FILE_MISSING_OR_INVALID
  • CSV_FILE_TOO_LARGE
  • LINE_NOT_READABLE
  • NUMBER_OF_COLUMNS_INCORRECT
  • COMMAND_MISSING_OR_INVALID
  • PROJECT_ID_MISSING
  • PROJECT_ID_INVALID
  • PROJECT_ID_UNKNOWN
  • PROJECT_NAME_MISSING_OR_INVALID
  • PROJECT_ACTIVE_FLAG_MISSING_OR_INVALID
  • PROJECT_BUDGET_HOURS_INVALID
  • PROJECT_SERVICES_FLAG_MISSING_OR_INVALID
  • WORKTIME_ENTRY_FOR_PROJECT_EXISTS_THUS_NO_DELETE
  • COMMENT_INVALID_OR_TOO_LARGE

Action code services

This action will return a list of all services (from the work time configuration).

Request URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/services

Request parameters

No additional request parameters are required or available.

Response data

The response will contain the requested data, encoded in UTF-8. The data will be returned as CSV (comma separated value). The first line will contain the column titles, subsequent lines will contain the working days information of one user, separated by semicolons.

The following columns will be returned:

  • ID of the service
  • Name
  • State
  • Billable
  • Comments
  • Creation date

The column "State" may contain the following values:

  • Active
  • Inactive

Action code holidays

This action will deliver a list of all bank holidays of one user or all users of a certain year. If you do not pass the year as parameter, the bank holidays of the current year will be returned.

Request URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/holidays

Request parameters

The following parameters can be passed as HTTP post parameters in the request:

Name of the parameter Mandatory Value
year no Year, 4-digits. For instance: 2024. If the year is invalid or not provided, the current year will be used.
userid no The user ID of the user for whom the bank holidays shall be returned. If the user ID is not provided, the bank holidays of all users will be returned.

Response data

The response will contain the requested data, encoded in UTF-8. The data will be returned as CSV (comma separated value). The first line will contain the column titles, subsequent lines will contain the information of one absence entry, separated by semicolons.

The following columns will be returned:

  • User ID
  • Date
  • Full / Half day (1 or 0.5)

Action worktimeaccountinperiod

eturns the data from the work time accounts view 'Overtime balance'.

Request URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/worktimeaccountinperiod

Request parameters

The following parameters can be passed as HTTP post parameters in the request:

Name of the parameter Mandatory Value
startdate yes Start date of the period for the calculation of the work time accounts.
Format: yyyy-mm-dd (for instance 2025-07-15)
enddate yes End date of the period for the calculation of the work time accounts.
The end date must be within the same or the following calendar year of the start date.
Format: yyyy-mm-dd (for instance 2025-08-31)
minutes no Value: true or false or empty or not provided
The returned data contains several time spans, for instance the working hours or the time balance. This data will be returned in the format '7.5 h' (for 7.5 hours).
If the request contains a parameter minutes=true, then the time spans will be returnd in minuts instead. So instead of '7.5 h' the API will return '450' (7 hours and 30 minutes = 450 minutes).

Response data

The response will contain the requested data, encoded in UTF-8. The data will be returned as CSV (comma separated value). The first line will contain the column titles, subsequent lines will contain the information of one user, separated by semicolons.

Columns and order

The first column contains the userid of the user's account.

The next columns in the CSV data stream will be the same as the columns when a user logs into his Timebutler user account and opens the working time balance view 'Working time in period', see there.

Action worktimeaccountbalance

Returns the data from the work time accounts view 'Overtime balance'.

Request URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/worktimeaccountbalance

Request parameters

The following parameter can be passed as HTTP post parameter in the request:

Name of the parameter Mandatory Value
date yes The date for the calculation of the working time balance accounts.
Format: yyyy-mm-dd (for instance 2025-07-15)
minutes no Value: true or false or empty or not provided
The returned data contains several time spans, for instance the working hours or the time balance. This data will be returned in the format '7.5 h' (for 7.5 hours).
If the request contains a parameter minutes=true, then the time spans will be returnd in minuts instead. So instead of '7.5 h' the API will return '450' (7 hours and 30 minutes = 450 minutes).

Response data

The response will contain the requested data, encoded in UTF-8. The data will be returned as CSV (comma separated value). The first line will contain the column titles, subsequent lines will contain the information of one user, separated by semicolons.

Columns and order

The first column contains the userid of the user's account.

The next columns in the CSV data stream will be the same as the columns when a user logs into his Timebutler user account and opens the working time balance view 'Overtime balance', see there.

Action code timeclock

You can start, pause, resume and stop the virtual time clock of your users.

Request URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/timeclock

Request parameters

The following parameters must be passed as HTTP post parameters in the request:

Name of the parameter Value
command

Valid commands are:

start
Start the virtual time clock. If the time clock is paused, then it will be resumed.

pause
Pause the virtual time clock.

resume
Resume the virtual time clock and continue the recording. if the time clock is not paused, then the time clock will be started.

stop
Stop the virtual time clock and save the time entry.

cancel
Stop the virtual time clock and discard the time entry.

status
Get the current state of the time clock

businesstripstart
Start a short business trip (only possible, if the time clock is running).

businesstripstop
Stop a short business trip (only possible, if the short bussiness trip has been started).
userid

The userid of the user for whom you want to control the virtual time clock.

You can obtain the list of userids by calling the API action users (see here). The userid values never change, so that you need to call the users action only once and save the list of userids in your system.
projectid
(optional)

The id of the project for this working time entry. The parameter is optional and it will only be read, if the command 'stop' is provided. It will be ignored for all other commands.

You can obtain the list of projectids by calling the API action projects (see here). The projectid values never change, so that you need to call the projects action only once and save the list of projectids in your system.
serviceid
(optional)

The id of the service for this working time entry. The parameter is optional and it will only be read, if the command 'stop' is provided. It will be ignored for all other commands.

You can obtain the list of serviceids by calling the API action services (see here). The serviceid values never change, so that you need to call the services action only once and save the list of services in your system.

Response data

The response will contain one of the following values (please see also the response data for the command status below):

OK

The command has been executed.

WARN_TIMECLOCK_ALREADY_RUNNING

The time clock is running and cannot be started twice.

WARN_TIMECLOCK_ALREADY_PAUSED

The time clock is already paused and cannot be paused twice.

WARN_TIME_ENTRY_SAVED_WITH_MODIFICATIONS

The time clock has been saved and the time entry has been saved. The time entry has been modified in order to comply with the requirements of the break regulations (break duration or maximum daily working time).

WARN_SHORT_BUSINESSTRIP_TIMECLOCK_NOT_RUNNING

The time clock is not running. The short business trip status can only be changed when the time clock is running.

WARN_SHORT_BUSINESSTRIP_ALREADY_STARTED

The business trip status is already active.

WARN_SHORT_BUSINESSTRIP_NOT_STARTED

The business trip status is inactive.

RESULT_ERR_INTERNAL_ERROR

An internal error ocurred. Please try again later.

RESULT_ERR_TIMETRACKING_FEATURE_NOT_ACT

The time tracking feature is disabled.

RESULT_ERR_COMMAND_INVALID

The command parameter is missing in the request or the command parameter value is invalid or unknown.

RESULT_ERR_USERID_INVALID

The userid parameter is missing in the request or the userid parameter value is invalid or unknown.

RESULT_ERR_PROJECTID_INVALID

The project id parameter is invalid or unknown.

RESULT_ERR_SERVICEID_INVALID

The project id parameter is invalid or unknown.

RESULT_ERR_TIMECLOCK_NOT_STARTABLE_MAY_OVERLAP

One or several working time entries exist for the current day. In order to avoid overlaps in time, the time clock may not be started.

RESULT_ERR_TIMECLOCK_STOPPED_WITHOUT_SAVE_DUE_TO_OVERLAPPING

One or several working time entries exist for the current day. If the entry for the time recording were to be saved now, the new time entry would overlap in time with one of the existing entries. The time clock has been stopped and the time entry has been discarded.

RESULT_ERR_TIMECLOCK_STOPPED_WITHOUT_SAVE_DUE_TO_UNRESOLVABLE_CHANGE_REQUIREMENTS

The new time entry does not comply with all requirements of the break regulation (break duration or maximum daily working time) and cannot be changed in a way that will meet comply with the requirements. The time clock has been stopped and the time entry has been discarded.

RESULT_ERR_TIMECLOCK_NOT_RUNNING

The time clock is not running and for this reason it cannot be paused or stopped.

RESULT_ERR_MIN_DURATION_OR_PAUSE_NOT_OK

The pause and the working time duration is less than 60 seconds. The time entry can not yet be saved.

Response data for command status

The command status will return more data than the other commands. The response will contain the requested data, encoded in UTF-8. The data will be returned as CSV (comma separated value). The first line will not contain the column titles but the response data, separated by semicolons, as follows:

The following columns will be returned:

  • Result code: For instance OK or RESULT_ERR_USERID_INVALID (see table above)
  • Status:
    • IDLE = time clock is not running
    • RUNNING = time clock is running
    • PAUSED = time clock paused
  • Start of the time clock: Timestamp in milliseconds since 1/1/1970 (if the time clock is not running and not paused, the return value will be 0)
  • Start of the current pause:Timestamp in milliseconds since 1/1/1970 (if the time clock is not paused, the return value will be 0)

Example:

OK;PAUSED;1560773445237;1560773701707

Action code timeimportbyevents

Offers commands to import time entries that have been generated by third party time tracking terminals. The time clock events can be imported (start/stop/pause/resume). Timebutler will create the work time entries that correspond to thetime clock events.

Request URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/timeimportbyevents

Request parameters

The following parameters need to be passed as HTTP post parameters in the request:

Name of the parameter Type Value
useridentification HTTP Parameter

In order to assign the imported data to the user accounts, the CSV data must contain either the email address or the employee number of the user. With this parameter you can notify whether the CSV data will contain the email address or the employee numer, as follows:

Parameter value email or parameter empty or not set: the CSV data will contain the email address.

Parameter value employeenumber: the CSV data will contain the employee number.

csvdatafile File The file with the CSV data to import. For more details, see below.

Format of the CSV file

The CSV file contains the data of the time clock events. Each line in the CSV file contains one event for one employee. The CSV may not contain headers. All lines will be parsed and processed. The delimiter is the semicolon (;).

Each line of the CSV file must contain the following data:

Column / Value Description Format / Example

First column

Email address or employee number of the user

 The request parameter "useridentification" (see above) determines whether this column will contain the email address or the employee number. Once set, the CSV file must either always contain the email address in this column or the employee number.

Email address or employee number

Examples:
sarah@example.com
EMP0209

Second column

Timestamp

 Date and time, when the event occurred (to-the-minute).

yyyy-MM-ddThh:mm
The T must be included as is, the other letters will be replaced by:

  • yyyy = year
  • MM = month 01-12
  • dd = day 01-31
  • hh = hour 00-23
  • mm = minute 00-59

Examples:
2025-03-31T17:58
(= 31. March 2025, 17:58 o'clock)

2025-12-02T07:08
(= 2. December 2025, 7:08 o'clock)

Third column

One of the following event types
START
STOP
PAUSE
RESUME

The event type determines, which event occurred on the given timestamp:

START
Time clock started

STOP
Time clock stopped

PAUSE
Time clock paused

RESUME
Time clock pause ended, resume time tracking

One of the 4 event types.

Examples:
START
PAUSE

Fourth column
(optional)

The id of the project for this working time entry.

The parameter is optional and it will only be read, if the event type STOP is provided. It will be ignored for all other event types.

You can obtain the list of projectids by calling the API action projects (see here). The projectid values never change, so that you need to call the projects action only once and save the list of projectids in your system.

Examples:
4711
32977

Fifth column
(optional)

The id of the service for this working time entry.

The parameter is optional and it will only be read, if the event type STOP is provided. It will be ignored for all other event types.

You can obtain the list of serviceids by calling the API action services (see here). The serviceid values never change, so that you need to call the services action only once and save the list of services in your system.

Examples:
4711
32977

Sixth column
(optional)

The comments for this working time entry.

The parameter is optional and it will only be read, if the event type STOP is provided. It will be ignored for all other event types.

The comments must be provided in one line and no line breaks can be added. Also, the semicolon cannot be used, because it separates the columns in the CSV file.

Example:
I had to leave early.

Requirements and conditions for the CSV file

CSV file examples

One work time entry from 9:43 o'clock until 17:33 o'clock with one pause between 11:45 o'clock and 12:17 o'clock, assigned to the project id 4711 and the service id 733, for one user:

sarah@example.com;2025-02-27T09:43;START
sarah@example.com;2025-02-27T11:45;PAUSE
sarah@example.com;2025-02-27T12:17;RESUME
sarah@example.com;2025-02-27T17:33;STOP;4711;733

Two work time entries for two users, in chronological order. The lines are not sorted by user, which is not a requirement and thus allowed:

sarah@example.com;2025-02-27T09:43;START
tom@example.com;2025-02-27T11:02;START
sarah@example.com;2025-02-27T11:45;PAUSE
sarah@example.com;2025-02-27T12:17;RESUME
tom@example.com;2025-02-27T16:05;STOP;;733;I had to leave early.
sarah@example.com;2025-02-27T17:33;STOP

Response data

The response will contain data as CSV, encoded in UTF-8. If no error occurred during the import, then the HTTP response will contain only 'OK'.

If at least one error occurred during the import, then the HTTP resopnse will contain errors for each line that caused the error, as follows: line #nn: error code

For instance: line #144: TIMESTAMP_INVALID

List of possible error codes:

  • INTERNAL_ERROR
  • CSV_FILE_MISSING_OR_INVALID
  • CSV_FILE_TOO_LARGE
  • LINE_NOT_READABLE
  • NUMBER_OF_COLUMNS_INCORRECT
  • COMMAND_MISSING_OR_INVALID
  • PROJECT_ID_MISSING
  • PROJECT_ID_INVALID
  • PROJECT_ID_UNKNOWN
  • PROJECT_NAME_MISSING_OR_INVALID
  • PROJECT_ACTIVE_FLAG_MISSING_OR_INVALID
  • PROJECT_BUDGET_HOURS_INVALID
  • PROJECT_SERVICES_FLAG_MISSING_OR_INVALID
  • WORKTIME_ENTRY_FOR_PROJECT_EXISTS_THUS_NO_DELETE
  • COMMENT_INVALID_OR_TOO_LARGE

Action code personnelfiles

This action returns the personnel file data of one or several users.

Request URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/personnelfiles

Request parameters

One of the following parameters can be passed as HTTP post parameter in the request. If no parameter is provided, the salary data of all users will be returned.

Parameter Oligatory Value
email no The email address of the user account, whose data shall be returned.
employeenumber no The employee number of the user account, whose data shall be returned.
userid no

The user id of the user account, whose data shall be changed.

You can obtain the list of userids by calling the API action users (see here). The userid values never change, so that you need to call the users action only once and save the list of userids in your system.

Response data

The response will contain the requested data, encoded in UTF-8. The data will be returned as CSV (comma separated value). The first line will contain the column titles, subsequent lines will contain the personnel data of every user, separated by semicolons.

Every company can configure and rename the fields of the digital personnel file and group them into categories. The following columns will be returned:

  • User ID
  • Employee number
  • Your individual personnel file field names, as follows:
    • Name of the group 1 | Name of the field 1
    • Name of the group 1 | Name of the field 2
    • Name of the group 1 | Name of the field 3
    • Name of the group 2 | Name of the field 1
    • Name of the group 2 | Name of the field 2
    • Name of the group 3 | Name of the field 1
    • Name of the group 3 | Name of the field 2
    • etc.

Example

If you configured the groups "Home address" containing the fields "Street", "ZIP code" and "City" and the group "Personal data" containing the fields "Place of birth" and "Marital status", then the following column titles will be returned:

  • User ID
  • Employee number
  • Home address | Street
  • Home address | ZIP Code
  • Home address | City
  • Personal data | Place of birth
  • Personal data | Marital status

Action code salaries

This action returns the salary data of one or several users.

Request URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/salaries

Request Parameters

One of the following parameters can be passed as HTTP post parameter in the request. If no parameter is provided, the salary data of all users will be returned.

Parameter Oligatory Value
email no The email address of the user account, whose data shall be returned.
employeenumber no The employee number of the user account, whose data shall be returned.
userid no

The user id of the user account, whose data shall be changed.

You can obtain the list of userids by calling the API action users (see here). The userid values never change, so that you need to call the users action only once and save the list of userids in your system.

Response data

The response will contain the requested data, encoded in UTF-8. The data will be returned as CSV (comma separated value). The first line will contain the column titles, subsequent lines will contain the salary of every user, separated by semicolons.

The following columns will be returned:

  • User ID
  • Employee number
  • Payment type
  • Valid from / Payment date
  • Valid until
  • Salary type / Bonus type
  • Gross amount
  • Currency
  • Hours per week
  • Comments

The column 'Payment type' may contain the following values:

  • Salary
  • Variable remuneration
  • Bonus payments

The column 'Salary type / Bonus type' is a free-text field and may contain any value entered by the user, for instance 'Fixed salary' or 'Bonus payment for exceeding sales goals'.

The column 'Hours per week' can be used to enter the weekly working hours.

The column 'Currency' may contain the following values:

  • AUD (Australian dollar)
  • BRL (Brazilian real)
  • GBP (British pound)
  • BGN (Bulgarian lev)
  • CAD (Canadian dollar)
  • CNY (Chinese yuan renminbi)
  • HRK (Croatian kuna)
  • CZK (Czech koruna)
  • DKK (Danish krone)
  • EUR (Euro)
  • HKD (Hong Kong dollar)
  • HUF (Hungarian forint)
  • ISK (Icelandic krona)
  • INR (Indian rupee)
  • IDR (Indonesian rupiah)
  • ILS (Israeli new shekel)
  • JPY (Japanese yen)
  • MYR (Malaysian ringgit)
  • MXN (Mexican peso)
  • NZD (New Zealand dollar)
  • NOK (Norwegian krone)
  • PHP (Philippine peso)
  • PLN (Polish zloty)
  • RON (Romanian new leu)
  • SGD (Singapore dollar)
  • ZAR (South African rand)
  • KRW (South Korean won)
  • SEK (Swedish krona)
  • CHF (Swiss franc)
  • THB (Thai baht)
  • TRY (Turkish lira)
  • USD (US dollar)

Code examples

Please replace the XXXXXXX with your API token.

Curl

curl -X POST 'https://timebutler.de/api/v1/absences' -d 'auth=XXXXXXX'

Python

import requests
url = 'https://timebutler.de/api/v1/absences'
params = {'auth': 'XXXXXXX'}
response = requests.post(url, params=params)
response.text

Java

public String requestTimebutlerApi()
{
  String postData = "auth=" + URLEncoder.encode("XXXXXXX", "UTF-8"); // java.net.URLEncoder
  String targetUrl = "https://timebutler.de/api/v1/absences";
  
  String responseTxt = "";
  
  URL url = new URL(targetUrl); // java.net.URL
  HttpURLConnection connection = (HttpURLConnection)url.openConnection(); // java.net.HttpURLConnection
  
  connection.setRequestMethod("POST");
  connection.setUseCaches(false);
  connection.setDoOutput(true);
  connection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
  connection.setRequestProperty("Content-Length", String.valueOf(postData.length()));
  connection.getOutputStream().write(postData.getBytes("UTF-8"));
  
  BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream(), "UTF-8")); // java.io.BufferedReader
  
  String line;
  while ((line = in.readLine()) != null) {
    responseTxt += line + "\n";
  }
  
  if (connection != null) {
    connection.disconnect();
  }
  
  return responseTxt;
}

Rust

use reqwest;

fn main() {
  request_timebutler_api()
}

fn request_timebutler_api() {

  let url = "https://timebutler.de/api/v1/absences";
  let params = [("auth", "XXXXXXX")];
  let client = reqwest::blocking::Client::new();
  let resp = match client
    .post(url)
    .form(&params)
    .send() {
      Ok(resp) => resp.text().unwrap(),
      Err(err) => panic!("Error: {}", err)
    };
}

Powershell

$url = "https://timebutler.de/api/v1/absences"
$body = @{
  auth = "XXXXXXX"
}

Invoke-RestMethod -Method 'Post' -Uri $url -Body $body -ContentType "application/x-www-form-urlencoded"

# If you want the output to be written into a file just add the following parameter to the last line above: -OutFile output.csv

Google Apps Script

function requestAbsences() {

  var apiUrl = "https://timebutler.de/api/v1/absences";
  var authtoken = "XXXXXXX";

  var formData = {
    'auth': authtoken
  };

  var options = {
    'method' : 'post',
    'payload' : formData
  };

  try {
    var response = UrlFetchApp.fetch(apiUrl, options);
    var responseData = response.getContentText();
  }
  catch (e) {
    Logger.log(e);
  }

};

Powerquery

let
  ApiKey = "XXXXXXX",
  baseUrl = "https://timebutler.de/api/v1/absences",
  headers = [#"Content-Type" = "application/x-www-form-urlencoded"],
  postData = "auth=" & ApiKey,
  response = Web.Contents(
    baseUrl,
      [
        Headers = headers,
        Content = Text.ToBinary(postData)
      ]
    ),
  csvResponse = Csv.Document(response, [Delimiter=";"]),
  #"PromoteHeader" = Table.PromoteHeaders(csvResponse, [PromoteAllScalars=true])
in
  #"PromoteHeader"

VBA (Excel, ...)

Sub requestTimebutlerApi()
 Set objHTTP = CreateObject("MSXML2.ServerXMLHTTP")
 URL = "https://timebutler.de/api/v1/absences"
 objHTTP.Open "POST", URL, False
 objHTTP.setRequestHeader "Content-Type", "application/x-www-form-urlencoded"
 objHTTP.Send ("auth=XXXXXXX")

 replyTXT = objHTTP.responseText

 If objHTTP.Status = "200" Then 'success
  MsgBox replyTXT
 Else
  MsgBox objHTTP
 End If
End Sub

 

To the top of the page