Arrow Back to Overview
API for online timekeeping: REST interface

API for online timekeeping: REST interface v2.1

Technical specification for software developers

The online timekeeping offers a REST interface for software developers. This REST service is also suitable for connecting time clocks, for example.

Requirements:

The REST API must be activated in the settings of the online time recording system (tab 'Security') and a password must be set.

Changes from version v1.1 to version v2.1

Please note the following changes when upgrading from version 1.1:

  • All resources with paths containing ../time-v2.1/.. are accessible in version 2.1 at ../time-v2.1/..
  • The Endpoint @GET /api/time-v2.1/timecategories has been renamed to @GET /api/time-v2.1/timetypes
  • The resource @POST /api/time-v2.1/createtimeentry has a new, optional parameter: comment
  • The resource @POST /api/time-v2.1/timeentries now additionally returns the property locked, which indicates whether the time entry has been locked. (Only for time tracking systems where the "Lockable time entries" feature is enabled.)

Testing options

A Hello World resource is available at:

A test resource for the login is available at:

Simple demo clients for all available REST API functions:

Description of resources

Ressource @GET /api/hello/sayhello

This resource for testing returns a hello.

Parameter:
none
Return value:
String
'Hello!'

Ressource @GET /api/hello/securedSayhello

This resource can be used to test the login. The login must be called beforehand.

Parameter:
none
Return value:
String
'Secured Hello!'

Ressource @POST /api/login

This resource can be used for login.

Parameter:
{loginemail, apipassword}
The login email of the admin is used as the login email. The API-password is set in the settings (tab 'Security'). Example: {"loginemail": "admin@gtsandbox.en", "apipassword": "12345678"}
Return value:
JSON web token
The returned token must be sent as a header with every request for authentication.

Ressource @GET /api/time-v2.1/timetypes

This resource returns a list of all time types.

Parameter:
none
Return value:
[{id, name}, ...]
List of time types in the format: time type id, time type name. Example: [{"id": "56941eee-86a7-4a8d-8af1-f78b0a688f32", "name": "working hours"}, ...]

Ressource @GET /api/time-v2.1/users

This resource returns a list of all users' login emails.

Parameter:
none
Return value:
[{loginemail}, ...]
The list of login emails of all users. Example: [{"admin@gtsandbox.en"}, ...]

Ressource @GET /api/time-v2.1/projects

This resource returns the list of projects.

Parameter:
none
Return value:
[{id, name}, ...]
The list of projects in the format: project id, project name. Example: [{"id": "56941eee-86a7-4a8d-8af1-f78b0a688f32", "name": "Demo Project"}, ...]

Ressource @GET /api/time-v2.1/projects/{useremail}

This resource returns a list of projects for a specific user.

Path parameter:
{useremail}
The login email of the user in question. Example: @GET /projects/maier@gtsandbox.en
Return value:
[{id, name}, ...]
The list of projects in the format: project id, project name. Example: [{"id": "56941eee-86a7-4a8d-8af1-f78b0a688f32", "name": "Demo Project"}, ...]

Ressource @GET /api/time-v2.1/timeentries?useremail={useremail}&start={start}&end={end}

This resource returns a user's time entries for a certain period of time.

Query parameter:
{useremail, start, end}
All time entries of the user are returned, the start time of which is between start and end. Start and end must be specified in the following format: YYYY-MM-DDTHH:MM:00 so e.g. 2024-12-24T17:03:00

Example of the path parameters for a query of the time entries over three days: Useremail=maier@somedomain.com, start=2024-07-23T00:00:00, end=2024-07-25T23:59:00
Return value:
[{id, starttime, ...}, ...]
The list of the time entries of the user in the specified period.

Example of a list of the time entries returned:
[{"id": "876b36db-2047-4f56-ab76-98221ca42600", "starttime": "2016-06-18T00:00:00", "endtime": "2016-06-19T00:00:00", "useremail": "admin@somedomain.com", "timetypeid": "56941eee-86a7-4a8d-8af1-f78b0a688f32", "projectid": "693fe9a3-bb48-4763-bb20-5fd9fa4ffeb2"}, ...]

Ressource @POST api/time-v2.1/createtimeentry

With this resource you can create a new time entry.

Parameter:
{starttime, endtime, useremail, timetypeid, projectid, comment}}
starttime and endtime must be specified in the following format: YYYY-MM-DDTHH:MM:00 - e.g.: 2017-03-23T10:15:00.
Specifying a projectid is optional.
Specifying a comment is optional.

Example of a time entry:
{"starttime": "2017-03-23T10:15:00", "endtime": "2017-03-23T18:21:00", "useremail": "maier@somedomain.com", "timetypeid": "83be5360-6067-4a09-a970-1ff2413d7101", "projectid": "2aeba501-ca09-41b2-a938-654d178914e4", "comment": "some test comment!"}
Return value:
[{id}, ...]
The list of id's of all time entries generated. In most cases, the list contains only one entry. Example: [{"2B301FBC-9594-4BDF-ABC4-6CD77714134D"}]

Ressource @DELETE /api/time-v2.1/deletetimeentry/{id}

With this resource you can delete a time entry.

Path parameter:
{id}
The ID of the time entry to be deleted. e.g.: 83be5360-6067-4a09-a970-1ff2413d7101

Return value:
None
Arrow Back to Overview

© 2026 Goodtime, Online Time Registration