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. Any request needs to use https always, not http. The URL for all requests is:

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

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://timebutler.de/api/v1/absences
users	Retrieve user data Returns a list of all users. https://timebutler.de/api/v1/users
holidayentitlement	Retrieve holiday entitlement data Returns a list of all users' holiday entitlement data. https://timebutler.de/api/v1/holidayentitlement
workdays	Retrieve user workdays data Returns a list of all workdays of all users. https://timebutler.de/api/v1/workdays
holidaysets	Retrieve holiday sets Returns a list of all holiday sets https://timebutler.de/api/v1/holidaysets
worktime	Retrieve working time entries Returns a list of working time entries. https://timebutler.de/api/v1/worktime
projects	Retrieve a list of all projects Returns a list of all projects (from the work time configuration). https://timebutler.de/api/v1/projects
projectsimport	Create, update or delete projects Offers commans to create, change or delete projects from the project list. https://timebutler.de/api/v1/projectsimport
services	Retrieve a list of all services Returns a list of all services (from the work time configuration). https://timebutler.de/api/v1/services
timeclock	Virtual time clock Offers commands for starting, pausing and stopping the virtual time clock. https://timebutler.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.de/api/v1/timeimportbyevents
personnelfiles	Request personnel file data Returns the personnel file data of one or all users. https://timebutler.de/api/v1/personnelfiles
salaries	Request salary data Returns the salary data of one or all users. https://timebutler.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://timebutler.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: 2023. 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 code users

This action will return the user data.

Request URL:

https://timebutler.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.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: 2023. 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 code workdays

This action will return all working days for all users.

Request URL:

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

This action will return a list of all holiday sets.

Request URL:

https://timebutler.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.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: 2023. 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.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.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 3072000 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.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 code timeclock

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

Request URL:

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

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.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: 2024-03-31T17:58 (= 31. March 2024, 17:58 o'clock) 2024-12-02T07:08 (= 2. December 2024, 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 3072000 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

Action code personnelfiles

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

Request URL:

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

Action code salaries

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

Request URL:

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

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