REST-API

The clockodo API allows you to connect clockodo to other systems. Accounting and project management applications or proprietary shell scripts are examples of useful mash-ups with clockodo.

clockodo REST API

Our API lets clockodo access other systems. Accounting and project management applications or proprietary shell scripts represent some of the useful mash-ups available with clockodo.

As a REST API, the interface allows clockodo data to be queried and amended over HTTP and JSON and the stopwatch to be controlled.


URL of the clockodo API

You get access to the interface by using the following address:

https://my.clockodo.com/api/[Ressourcen-Typ]

The resource type represents a class of your data. In the menu, you will find detailed descriptions for each resource type. For example you can find informations about managing the resource type "entry" on the page "/api/entries".

 

Once you request a specific resource, for example, retrieve information about exactly one time entry, the URL changes as follows:

https://my.clockodo.com/api/[Ressourcen-Typ]/[Ressourcen-ID]

HTTP Verbs

In order to tell the API which operations you want to perform on the resources, the so-called verbs of the HTTP protocol are used. The following operations are usually possible:

GET Query a list of all the resources of the selected resource type
GET, by handing over a resource ID in the URL Query exactly one resource
POST Create a new resource
PUT, by handing over a resource ID in the URL Update or edit a resource
DELETE Delete a resource (for most resources, the clockodo API does not delete it finally, but does disable it)

Authentication

To get to your data through the API, you have to authenticate with the so-called API key. There are two different ways.

With the http-Header:

X-ClockodoApiUser: [E-Mail-Adresse]
X-ClockodoApiKey: [API-Key]

 

Or with the basic authentication of the HTTP protocol:

User: [E-Mail-Adresse]
Password: [API-Key]

For each co-worker a separate API access is available, taking into account the individual access rights.

Every co-worker will find his API key in the menu item "Personal data" in his clockodo account.


Localisation

 

Some response values of the API are localized. For example some texts describing dates, error messages and others. In order to switch between available languages (en/de), please use the Accept-Language header of the HTTP protocol:

Accept-Language: en

Response codes

 

The API responds to requests with the status code of the HTTP protocol.

200 - OK The request was successful
400 - Bad Request The request was defective (for example missing parameter)
401 - Unauthorized Authentication failed
404 - Not found The requested resource was not found
409 - Conflict A resource with the data already exists
500 - Internal Server Error An unknown error occurred

Additional request parameters

 

Certain resources provide a lot of data. Therefore, for these resources a „page by page output“ is active. So you get back a maximum of 1000 elements per call. With the additional request parameter "page" you can then access other elements.

Additional request parameters page (integer)
Additional contents of the response
'paging': {
  'items_per_page': [integer],
  'current_page': [integer],
  'count_pages': [integer],
  'count_items': [integer]
}

Note: Currently the paging is only active for the resource "entries".


Example calls

Example of retrieving all users with cURL using the basic authentication:
curl -v 
  -X GET \ 
  -u [E-Mail-Adresse]:[API-Key] \ 
  https://my.clockodo.com/api/services
Example of retrieving all users with cURL with authentication through the HTTP header:
curl -v 
  -X GET \ 
  -H 'X-ClockodoApiUser: [E-Mail-Adresse]' \ 
  -H 'X-ClockodoApiKey: [API-Key]' \ 
  https://my.clockodo.com/api/services
Example call of creating a service:
curl -v 
  -X POST \ 
  -H 'X-ClockodoApiUser: [E-Mail-Adresse]' \ 
  -H 'X-ClockodoApiKey: [API-Key]' \ 
  --data "name=Testleistung" \
  https://my.clockodo.com/api/services