The Clockodo API:
Connection of Clockodo to other systems

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/[resource type]

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/v2/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/[resource type]/[resource 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: [email address]
X-ClockodoApiKey: [API key]

Or with the basic authentication of the HTTP protocol:

User: [email address]
Passwort: [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.

Client-Identification

Every request to our API must provide identification of the calling application, including the email address of a technical contact person. For this, the following HTTP header must be used:

X-Clockodo-External-Application: [name of application or company];[email address]

Example:

X-Clockodo-External-Application: Clockodo;admin@clockodo.com

Localization: Language & formats

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/fr), 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
403 - Forbidden Insufficient access rights for the requested resource
404 - Not found The requested resource was not found
405 - Method Not Allowed The requested endpoint cannot be used
409 - Conflict A resource with the data already exists
429 - Too many requests Too many requests to an endpoint in a certain period of time
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, meaning the number of elements returned per call is limited. 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 paging is only active for the resources "entries", "entriesTexts", "customers" and "projects".

Example calls

Example of retrieving all users with cURL using the basic authentication:
curl -v 
  -X GET \ 
  -u [email address]:[API key] \ 
  -H 'X-Clockodo-External-Application: [name of application];[email address]' \ 
  'https://my.clockodo.com/api/v2/services'
Example of retrieving all users with cURL with authentication through the HTTP header:
curl -v 
  -X GET \ 
  -H 'X-ClockodoApiUser: [email address]' \ 
  -H 'X-ClockodoApiKey: [API key]' \ 
  -H 'X-Clockodo-External-Application: [name of application];[email address]' \ 
  'https://my.clockodo.com/api/v2/services'
Example call for creating a service:
curl -v 
  -X POST \ 
  -H 'X-ClockodoApiUser: [email address]' \ 
  -H 'X-ClockodoApiKey: [API key]' \ 
  -H 'X-Clockodo-External-Application: [name of application];[email address]' \ 
  --data "name=Testleistung" \
  'https://my.clockodo.com/api/v2/services'
stripes illustration
Contact us!

Our Customer-Success-Team will answer your questions.

Contact now!
Test all functions 14 days free of charge
By submitting this form you accept our terms and conditions and our privacy policy and you confirm that you will use Clockodo as a commercial user.

Take advantage of the experience of 10,000 other companies:

Bechtle Mannheim LogoBechtlePeerigon LogoPeerigon GmbH
Phoenix Logistik LogoPhoenix LogistikFieda LogoFidea