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://timebutler.fidiapharma.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://timebutler.fidiapharma.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 )

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://timebutler.fidiapharma.de/api/v1/absences
useraccount	Edit user accounts Modify a user account. https://timebutler.fidiapharma.de/api/v1/useraccount
managerassignment	Change the manager assigment Change the assignment of users to managers https://timebutler.fidiapharma.de/api/v1/managerassignment
users	Retrieve user data Returns a list of all users. https://timebutler.fidiapharma.de/api/v1/users
holidayentitlement	Retrieve holiday entitlement data Returns a list of all users' holiday entitlement data. https://timebutler.fidiapharma.de/api/v1/holidayentitlement
setholidayentitlement	Change the holiday entitlement values Change the holiday entitlement values for an employee https://timebutler.fidiapharma.de/api/v1/setholidayentitlement
workdays	Retrieve user workdays data Returns a list of all workdays of all users. https://timebutler.fidiapharma.de/api/v1/workdays
setworkdays	Change the work days of a user change the work days of a user https://timebutler.fidiapharma.de/api/v1/setworkdays
holidaysets	Retrieve holiday sets Returns a list of all holiday sets https://timebutler.fidiapharma.de/api/v1/holidaysets
worktime	Retrieve working time entries Returns a list of working time entries. https://timebutler.fidiapharma.de/api/v1/worktime
projects	Retrieve a list of all projects Returns a list of all projects (from the work time configuration). https://timebutler.fidiapharma.de/api/v1/projects
projectsimport	Create, update or delete projects Offers commans to create, change or delete projects from the project list. https://timebutler.fidiapharma.de/api/v1/projectsimport
services	Retrieve a list of all services Returns a list of all services (from the work time configuration). https://timebutler.fidiapharma.de/api/v1/services
worktimeaccountinperiod	Work time accounts - Working time in period Returns the data from the work time accounts view 'Working time in period' https://timebutler.fidiapharma.de/api/v1/worktimeaccountinperiod
worktimeaccountbalance	Work time accounts - Overtime balance Returns the data from the work time accounts view 'Overtime balance' https://timebutler.fidiapharma.de/api/v1/worktimeaccountbalance
timeclock	Virtual time clock Offers commands for starting, pausing and stopping the virtual time clock. https://timebutler.fidiapharma.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://timebutler.fidiapharma.de/api/v1/timeimportbyevents

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://timebutler.fidiapharma.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 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".

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:

Action useraccount

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

Request URL:

https://timebutler.fidiapharma.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	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 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
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_DE German en_UK English en_US English (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://timebutler.fidiapharma.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://timebutler.fidiapharma.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.

Action code holidayentitlement

This action will return the users' holiday entitlement data.

Request URL:

https://timebutler.fidiapharma.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.

Action setholidayentitlement

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

Request URL:

https://timebutler.fidiapharma.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)

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://timebutler.fidiapharma.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.

Action setworkdays

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

Request URL:

https://timebutler.fidiapharma.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	Deduct the given number of minutes for every calendar day with work time entries. Value 0 or parameter not provided: no rounding.

¹⁾ 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.

• If you want to create only one period, then provide the parameters group_1_valid_from to group_1_holiday_set_id only (you may also add the parameters for the time tracking).
• If you want to create two periods, then provide the following parameters:
  • the parameters group_1_valid_from to group_1_holiday_set_id (you may also add the parameters for the time tracking).
  • and the parameters group_2_valid_from to group_2_holiday_set_id (you may also add the parameters for the time tracking).

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://timebutler.fidiapharma.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.

Action code worktime

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

Request URL:

https://timebutler.fidiapharma.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.

Action code projects

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

Request URL:

https://timebutler.fidiapharma.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.

Action projectsimport

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

Request URL:

https://timebutler.fidiapharma.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

• Each line must contain exactly one command and one set of project data
• If the command DELETE is provided, only the ID of the project must be provided. The other columns may remain empty, but must still be provided, so that the number of semicolons must be correct.
• No headers, only lines that contain data
• he maximum size of the CSV file is 9216000 bytes.

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:

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:

If the input line could not be processed:

• The '#n' will be replaced by the line number.
• The [PROJECT-ID] will be replaced by the ID of the project that has been created / changed / deleted.
• The [ERRORCODE] will be replaced by the error code (see below).

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

Error codes

List of possible error codes:

Action code services

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

Request URL:

https://timebutler.fidiapharma.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.

Action worktimeaccountinperiod

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

Request URL:

https://timebutler.fidiapharma.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://timebutler.fidiapharma.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://timebutler.fidiapharma.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
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):

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:

Example:

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://timebutler.fidiapharma.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

Requirements and conditions for the CSV file

• Each line must contain exactly one event
• No headers, only lines that contain data
• The events must be listed in chronological sequence, starting with the oldest and ending with the newest event
• For a user the START event must be the first entry, then PAUSE or RESUME may follow and finally a STOP entry must be provided. One file may contain several of those event groups for the same or different users.
• The lines for one user must not necessarily be one below the other - instead the events from different users can be listed, as long as the chronological sequence is guranteed.
• If an event group for one user does not end with a STOP event, then the events of this event group will be ignored (for instance start at 9:45 o'clock, pause at 12:03 o'clock and no further events after that).
• Within one event group the START and STOP event must not exceed two calendar days.
• The maximum size of the CSV file is 9216000 bytes.

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:

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:

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

To the top of the page