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.

api/v2/entries: Manage entries

The first version of this endpoint (api/entries) is deprecated and will not be available after Dec 31, 2022.


Object type "entry"

Basic information

included in all entry types

Parameter Type Description
id integer ID of the entry
customers_id integer ID of the corresponding customer
projects_id integer|null ID of the corresponding project
users_id integer ID of the corresponding co-worker
billable integer Is the entry billable? 0: not billable, 1: billable, 2: already billed
texts_id integer|null ID of the description text
time_since string Starting time in format ISO 8601 UTC, e.g. "2021-06-30T12:34:56Z"
time_until string|null End time, NULL if entry is running in format ISO 8601 UTC, e.g. "2021-06-30T12:34:56Z"
time_insert string Insert time in format ISO 8601 UTC, e.g. "2021-06-30T12:34:56Z"
time_last_change string Time at which the entry has been changed the last time in format ISO 8601 UTC, e.g. "2021-06-30T12:34:56Z"
[customers_name] string Name of the corr. customers Only in list function with enhanced list mode enabled
[projects_name] string|null Name of the corr. project Only in list function with enhanced list mode enabled
[users_name] string Name of the corr. co-worker Only in list function with enhanced list mode enabled
[text] string|null description text Only in list function with enhanced list mode enabled
[revenue] float Revenue of the entry Only with necessary access rights and only in list function with enhanced list mode enabled
type integer Type of the entry 1: time entry, 2: lump sum value, 3: entry with lump sum service

Type 1: time entry

Parameter Type Description
services_id integer ID of the corresponding service
duration integer Duration of the entry in seconds
offset integer The time correction of the entry in seconds. Is set if the duration differs from the period between start and end.
clocked boolean Entry was stopped with the clock
clocked_offline boolean Entry was clocked offline
time_clocked_since string|null Time at which the clock was started in format ISO 8601 UTC, e.g. "2021-06-30T12:34:56Z"
time_last_change_worktime string Time at which worktime relevant details were changed the last time in format ISO 8601 UTC, e.g. "2021-06-30T12:34:56Z"
hourly_rate float Hourly rate Only with necessary access rights
[services_name] string Name of the corr. service Only in list function with enhanced list mode enabled

Type 2: lump sum value

Parameter Type Description
services_id integer ID of the corresponding service
lumpsum float Value of the lump sum entry
[services_name] string Name of the corr. service Only in list function with enhanced list mode enabled

Type 3: Entry with lump sum service

Parameter Type Description
lumpsum_services_id integer ID of the corresponding lumpsum service
lumpsum_services_amount float amount of the lump sum service
lumpsum_services_price float Price per unit Only in list function with enhanced list mode enabled

List entries

Request
GET /api/v2/entries
Required parameters time_since string in format ISO 8601 UTC, e.g. "2021-06-30T12:34:56Z"
time_until string in format ISO 8601 UTC, e.g. "2021-06-30T12:34:56Z"
Optionale Parameter filter[users_id] integer
filter[customers_id] integer
filter[projects_id] integer
filter[services_id] integer
filter[lumpsum_services_id] integer
filter[billable] integer 0, 1 or 2
With the request filter[billable]=2 you only receive entries which are billable and already billed
filter[text] / filter[texts_id] string / integer
filter[budget_type] string strict, strict-completed, strict-incomplete, soft, soft-completed, soft-incomplete, without, without-strict
calc_also_revenues_for_projects_with_hard_budget boolean By default, revenues for projects with hard budgets will no be calculated. If you activate this option, the sum of all revenues to this project can be more than the project budget

Only für enhanced_list=1
enhanced_list boolean Enables the output of additional information

Please note that listing entries requires the restriction to a time period with the parameters above. Additionally, you can filter the entries by parameters.

Because the result can have many entries, the use of page-by-page-output is enabled for this request.

Do also note, that GET parameters have to be URL encoded. Using cURL, the request has to look like in the following example. Most libraries and applications (REST clients) do encode the parameters automatically.

Example curl request
curl -v 
  -X GET \ 
  -H 'X-ClockodoApiUser: [email adress]' \ 
  -H 'X-ClockodoApiKey: [API key]' \ 
  -H 'X-Clockodo-External-Application: [name of application];[email address]' \ 
  "https://my.clockodo.com/api/v2/entries?time_since=2021-01-01%2000:00:00&time_until=2021-02-01%2000:00:00"
Answer
{
  "paging": [paging information],
  "filter": [list of respected filters],
  "entries": 
  {
    [object of type entry],
    [object of type entry],
    ...
  }
}

Please refer to the description of the page-by-page-output.


Get entry

Request
GET /api/v2/entries/[ID]
Answer
{
  "entry": [object of type entry]
}

Add entry

Request
POST /api/v2/entries

Type 1: Time entry

Required parameters customers_id, services_id, billable, time_since, time_until
Optional parameters users_id, duration, hourly_rate, projects_id, text

Type 2: Lump sum value

Required parameters customers_id, services_id, lumpsum, billable, time_since
Optional parameters users_id, projects_id, text

Type 3: Entry with lump sum service

Required parameters customers_id, lumpsum_services_id, lumpsum_services_amount, billable, time_since
Optional parameters users_id, projects_id, text
Answer
{
  "entry": [object of type entry]
}

Edit entry

Request
PUT /api/v2/entries/[ID]
Required parameters keine
Optional parameters customers_id, projects_id, services_id, lumpsum_services_id, users_id, billable, text, duration, lumpsum, lumpsum_services_amount, hourly_rate, time_since, time_until
Answer
{
  "entry": [object of type entry]
}

Delete entry

Request
DELETE /api/v2/entries/[ID]
Answer
{
  "success": true
}