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
}