« Back to Overview
API for online timekeeping: REST interface

API for online timekeeping: REST interface v2.1

Here you can find the documentation for the old version REST-API v1.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. Note: The same password is also used for the web service interface.

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

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: JJJJ-TT-MMTHH:MM:00 so e.g. 2024-23-03T17:03:00

Example of the path parameters for a query of the time entries over three days: Useremail=maier@somedomain.com, start=2024-23-07T00:00:00, end=2024-25-07T23: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-DD-MMTHH:MM:00 - e.g.: 2017-23-03T10:15:00.
Specifying a projectid is optional.
Specifying a comment is optional.

Example of a time entry:
{"starttime": "2017-23-03T10:15:00", "endtime": "2017-23-03T18: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
« Back to Overview

© 2005 - 2025 Goodtime Online Time Registration