Clockify API
By using Clockify's REST-based API, you can push and pull data to and from Clockify, and integrate it with other systems. Feel free to post any questions you have on Stack Overflow with the clockify tag, or contact us if something is not working properly.
To get reports via API, you're going to have to use the base endpoint for reports (which is different from the one for manipulating other objects).
Authentication
All your requests should include "X-Api-Key" in request header, containing your API key.
If your workspace is on a subdomain (eg. something.clockify.me), you'll need to generate a new API key in your Profile Settings that will work just for that workspace.
If you're a self-hosted user, you'll have to use a different API base endpoint: "https://yourcustomdomain.com/api" and "https://yourdomain.com/reports" (you can find exact endpoints when you go to "https://youdomain.com/web/boot").
Rate limiting
There's a rate limit of 10 requests per second. If you get over the limit, you'll get "Too many requests" error.
API examples
See examples of calls to Clockify REST API in various programming languages (and add your own examples).
Change log
Sep 9 2021
- Fixed: Introduced max 5,000 page-size limit on all base endpoints, and 1,000 for reporting endpoints.
Aug 5 2021
- New: Added custom field type in responses for time entry endpoints
Jun 3, 2021
- Fixed: Response for Detailed report now returns the right timezone offset for start/end time
- New: Filter reports by invoicingState and approvalState
May 10, 2021
- Added missing costRate in user object
- Added missing hourlyRate and costRate for tasks on projects
- Added includeRoles query parameter for GET users (returns users and project where user is manager)
Mar 31, 2021
- Added missing clientId in Detailed report response
- New endpoint: PATCH time entries as invoiced
Dec 23, 2020
- New header parameter "Clockify-Action-Metadata" for API requests that will be returned via webhook
Dec 14, 2020
- Added budget and cost rate to project response
- New endpoint: UPDATE project estimate (time or budget)
API Base Endpoint
https://api.clockify.me/api/v1API Base Endpoint for Reports
https://reports.api.clockify.me/v1Example request
curl -H "content-type: application/json" -H "X-Api-Key: yourAPIkey" -X GET https://api.clockify.me/api/v1/userTerms of Service: https://clockify.me/terms
Webhooks
Webhooks can notify your app when something happens in Clockify (eg. when a timer is started or an entry is deleted).
Available webhooks in Clockify
- Timer started/stopped (me/anyone)
- Time entry created manually/updated/deleted (me/anyone)
- Client/project/task/tag created on workspace
Notes
You can access webhooks in your Profile settings (beneath the API key)
Each user can have up to 10 webhooks per workspace. A workspace can have 100 webhooks in total.
Only workspace admins can create webhooks.
Only the user who created the webhook can see and modify it.
You can see logs of sent webhooks by clicking on a webhook you've created. There you can also send a test webhook. Logs older than 7 days are deleted.
You can find your webhook's signing secret by clicking on the webhook's eye icon Webhooks page (or when you open edit screen of the webhook). Then, to verify the webhook with the signing secret, compare it with the "clockify-signature" value in the response header.
To avoid endless update loops, you can send "Clockify-Action-Metadata" parameter via API request header, and its value will be passed along by the webhook event it triggered. Example: You can send "update time entry" request and pass along "Clockify-Action-Metadata: MyRequestId123" in the header, and when the "time entry updated" webhook is triggered, you'll receive "Clockify-Action-Metadata: MyRequestId123" in the webhook.
Client
Endpoints for manipulating CLIENT resource
Find clients on workspace
If true, you'll get only archived clients. If false, you'll get only active clients.
If provided, clients will be filtered by name
page
max page-size 5000
NAME
ASCENDING, DESCENDING
OK
Unauthorized
Forbidden
Not Found
Response Content-Types: */*
Response Example (200 OK)
[
{
"id": "5b1e52ff0cb8792ed75992c1",
"name": "Client X",
"workspaceId": "5c0fe3290cl84304845dbf1f",
"archived": "false"
}
]
Add a new client to workspace
Request Content-Types: application/json
Request Example
{
"name": "Client"
}
Created
Client with that name already exists on workspace
Unauthorized
Forbidden
Not Found
Response Content-Types: */*
Response Example (201 Created)
{
"id": "5b1e52ff0cb8792ed75992c1",
"name": "Client",
"workspaceId": "5c0fe3290cl84304845dbf1f"
}
Update client
Controls whether archiving client will result in archiving all projects of given client
Request Content-Types: application/json
Request Example
{
"archived": false,
"name": "Client"
}
OK
Created
Bad Request
Unauthorized
Forbidden
Not found
Response Content-Types: */*
Response Example (200 OK)
{
"archived": true,
"id": "5bf6d2b9b079876a34621638",
"name": "Client",
"workspaceId": "5bfd36c4b0798777049512e3"
}
Delete client
OK
No Content
Bad Request
Unauthorized
Forbidden
Not found
Response Content-Types: */*
Response Example (200 OK)
{
"archived": true,
"id": "5bf6d2b9b079876a34621638",
"name": "Client",
"workspaceId": "5bfd36c4b0798777049512e3"
}
Project
Endpoints for manipulating PROJECT resource
Get all projects on workspace
If true, you'll get only archived projects. If false, you'll get only active projects.
If provided, projects will be filtered by name.
page
max page-size 5000
If provided, projects will be filtered by billable status.
If provided, projects will be filtered by client ID(s).
If provided, projects will be filtered by whether they have a client.
Possible values: ACTIVE, ARCHIVED
If provided, projects will be filtered by user ID(s) who have access.
If provided, projects will be filtered by whether they have users.
Possible values: ACTIVE, INACTIVE
If provided, projects will be filtered by whether they are used as a template.
Possible values: NAME, CLIENT_NAME, DURATION.
Possible values: ASCENDING, DESCENDING.
OK
Unauthorized
Forbidden
Not Found
Response Content-Types: */*
Response Example (200 OK)
[
{
"id": "5e4e42156fe9056cfb00252",
"name": "Project",
"hourlyRate": null,
"clientId": "",
"workspaceId": "5e4e38caq7668c16662b303a",
"billable": true,
"memberships": [
{
"userId": "5a0ab5acb2d987125438b60f",
"hourlyRate": null,
"targetId": "5e4e38f156fe9056cfb00252",
"membershipType": "PROJECT",
"membershipStatus": "ACTIVE"
}
]
"color": "#4CAF50",
"estimate": {
"estimate": "PT0S",
"type": "AUTO"
}, // Legacy field, same info as timeEstimate
"archived": false,
"duration": "PT0S",
"clientName": "",
"note": "",
"template": false,
"public": false,
"costRate": null,
"budgetEstimate": null,
"timeEstimate": {
"estimate": "PT0S",
"type": "AUTO",
"resetOption": null,
"active": true
}
}
]
Find project by ID
OK
Unauthorized
Forbidden
Not Found
Response Content-Types: */*
Response Example (200 OK)
{
"id": "5e4e42156fe9056cfb00252",
"name": "Project",
"hourlyRate": null,
"clientId": "",
"workspaceId": "5e4e38caq7668c16662b303a",
"billable": true,
"memberships": [
{
"userId": "5a0ab5acb2d987125438b60f",
"hourlyRate": null,
"targetId": "5e4e38f156fe9056cfb00252",
"membershipType": "PROJECT",
"membershipStatus": "ACTIVE"
}
]
"color": "#4CAF50",
"estimate": {
"estimate": "PT0S",
"type": "AUTO"
}, // Legacy field, same info as timeEstimate
"archived": false,
"duration": "PT0S",
"clientName": "",
"note": "",
"template": false,
"public": false,
"costRate": null,
"budgetEstimate": null,
"timeEstimate": {
"estimate": "PT0S",
"type": "AUTO",
"resetOption": null,
"active": true
}
}
Add a new project to workspace
Request Content-Types: application/json
Request Example
{
"name": "My API Project",
// OPTIONAL
"clientId": "",
"isPublic": "false",
"color": "#f44336",
"note": "This is project's note",
"billable": "true",
"public": false
}
Created
Project with that name already exists on workspace.
Unauthorized
Forbidden
Not Found
Response Content-Types: */*
Response Example (201 Created)
{
"archived": "false",
"billable": "true",
"clientId": "",
"clientName": "",
"color": "string",
"duration": "PT0S",
"estimate": {
"estimate": "PT0S",
"type": "MANUAL"
}, // Legacy field, same info as timeEstimate
"hourlyRate": {
"amount": "0",
"currency": "USD"
},
"id": "5b1e6b160cb8793dd93ec120",
"memberships": [
{
"hourlyRate": {
"amount": "10",
"currency": "USD"
},
"membershipStatus": "ACTIVE",
"membershipType": "PROJECT",
"targetId": "5b1e6b160cb8793dd93ec120",
"userId": "5a9e9a39b079874a74cfa980"
}
],
"name": "My Api Project",
"public": false,
"costRate": null,
"budgetEstimate": null,
"timeEstimate": {
"estimate": "PT0S",
"type": "AUTO",
"resetOption": null,
"active": true
},
"workspaceId": "5b152d9b0cb8797f86cbe14f",
}
Update project on workspace
MANUAL type enables one fixed estimate for the whole project. AUTO type enables task-based project estimate. If AUTO is enabled, estimate duration doesn't matter.
Request Content-Types: application/json
Request Example
{
"name": "My API Project",
"clientId": "",
"isPublic": "false",
"hourlyRate": {
"amount": 3600
},
"color": "#f44336",
"note": "This is project's note (optional)",
"billable": "true",
"archived": "true"
}
Created
Project with that name already exists on workspace.
Unauthorized
Forbidden
Not Found
Response Content-Types: */*
Response Example (201 Created)
{
"archived": "false",
"billable": "true",
"clientId": "",
"clientName": "",
"color": "string",
"duration": "PT0S",
"estimate": {
"estimate": "PT1H0M0S",
"type": "MANUAL"
},
"hourlyRate": {
"amount": "0",
"currency": "USD"
},
"id": "5b1e6b160cb8793dd93ec120",
"memberships": [
{
"hourlyRate": {
"amount": "10",
"currency": "USD"
},
"membershipStatus": "ACTIVE",
"membershipType": "PROJECT",
"targetId": "5b1e6b160cb8793dd93ec120",
"userId": "5a9e9a39b079874a74cfa980"
}
],
"name": "My Api Project",
"public": false,
"costRate": null,
"budgetEstimate": null,
"timeEstimate": {
"estimate": "PT1H0M0S",
"type": "MANUAL",
"resetOption": null,
"active": null
},
"workspaceId": "5b152d9b0cb8797f86cbe14f"
}
Update project estimate
Choose if estimate is in time or budget. Only one of the two can be active. If you need "No estimate", then send empty "{}" request, or set both active fields as false.
Choose if estimate resets each month. Possible values: null and MONTHLY
Possible values: MANUAL (for estimating whole project) and AUTO (to enable task-based estimate)
Request Content-Types: application/json
Request Example
{
"timeEstimate": {
"estimate": "PT1H0M0S",
"type": "MANUAL",
"active": false,
"resetOption": MONTHLY
},
"budgetEstimate": {
"estimate": 1100,
"type": "MANUAL",
"active": true,
"resetOption": null
}
}
OK
Only one type of estimate can be active at a time.
Unauthorized
Forbidden
Not Found
Response Content-Types: */*
Response Example (201 Created)
{
"archived": "false",
"billable": "true",
"clientId": "",
"clientName": "",
"color": "string",
"duration": "PT0S",
"estimate": {
"estimate": "PT1H0M0S",
"type": "AUTO"
},
"hourlyRate": {
"amount": "0",
"currency": "USD"
},
"id": "5b1e6b160cb8793dd93ec120",
"memberships": [
{
"hourlyRate": {
"amount": "10",
"currency": "USD"
},
"membershipStatus": "ACTIVE",
"membershipType": "PROJECT",
"targetId": "5b1e6b160cb8793dd93ec120",
"userId": "5a9e9a39b079874a74cfa980"
}
],
"name": "My Api Project",
"public": false,
"costRate": null,
"budgetEstimate": {
"estimate": 1100,
"type": "MANUAL",
"resetOption": MONTHLY,
"active": true
},
"timeEstimate": {
"estimate": "PT0S",
"type": "AUTO",
"resetOption": null,
"active": false
},
"workspaceId": "5b152d9b0cb8797f86cbe14f"
}
Update project memberships
Request Content-Types: application/json
Request Example
{
"memberships": [
{
"userId": "5ef31421f9ef6228d72d8833", (can be group ID or user ID)
"hourlyRate": {
"amount": 2000
} (optional)
}
]
}
OK
User or group is not a member of this workspace.
Unauthorized
Forbidden
Not Found
Response Content-Types: */*
Response Example (201 Created)
{
"archived": "false",
"billable": "true",
"clientId": "",
"clientName": "",
"color": "string",
"duration": "PT0S",
"estimate": {
"estimate": "PT1H0M0S",
"type": "AUTO"
},
"hourlyRate": {
"amount": "0",
"currency": "USD"
},
"id": "5b1e6b160cb8793dd93ec120",
"memberships": [
{
"userId": "5ef31421f9ef6228d72d8833", (can be groupID or userID)
"hourlyRate": {
"amount": 2000,
"currency": "USD"
},
"targetId": "5efee823462f493d3bc08302", (project ID)
"membershipType": "PROJECT",
"membershipStatus": "ACTIVE"
}
],
"name": "My Api Project",
"public": "false",
"costRate": null,
"budgetEstimate": null,
"timeEstimate": {
"estimate": "PT0S",
"type": "AUTO",
"resetOption": null,
"active": true
},
"workspaceId": "5b152d9b0cb8797f86cbe14f"
}
Update project template
Request Content-Types: application/json
Request Example
{
"isTemplate": "true"
}
Created
Project with that name already exists on workspace.
Unauthorized
Forbidden
Not Found
Response Content-Types: */*
Response Example (201 Created)
{
"archived": "false",
"billable": "true",
"clientId": "",
"clientName": "",
"color": "string",
"duration": "PT0S",
"estimate": {
"estimate": "PT1H0M0S",
"type": "AUTO"
},
"hourlyRate": {
"amount": "0",
"currency": "USD"
},
"id": "5b1e6b160cb8793dd93ec120",
"memberships": [
{
"hourlyRate": {
"amount": "10",
"currency": "USD"
},
"membershipStatus": "ACTIVE",
"membershipType": "PROJECT",
"targetId": "5b1e6b160cb8793dd93ec120",
"userId": "5a9e9a39b079874a74cfa980"
}
],
"name": "My Api Project",
"public": "false",
"public": false,
"costRate": null,
"budgetEstimate": null,
"timeEstimate": {
"estimate": "PT0S",
"type": "AUTO",
"resetOption": null,
"active": true
},
"workspaceId": "5b152d9b0cb8797f86cbe14f"
}
Delete project from workspace
OK
No Content
Project with specified id not found
Unauthorized
Forbidden
Response Content-Types: */*
Response Example (200 OK)
{
"archived": "false",
"billable": "true",
"clientId": "",
"clientName": "",
"color": "string",
"duration": "PT0S",
"estimate": {
"estimate": "PT1H0M0S",
"type": "AUTO"
},
"hourlyRate": {
"amount": "0",
"currency": "USD"
},
"id": "5b1e6b160cb8793dd93ec120",
"memberships": [
{
"hourlyRate": {
"amount": "10",
"currency": "USD"
},
"membershipStatus": "ACTIVE",
"membershipType": "PROJECT",
"targetId": "5b1e6b160cb8793dd93ec120",
"userId": "5a9e9a39b079874a74cfa980"
}
],
"name": "My Api Project",
"public": "false",
"public": false,
"costRate": null,
"budgetEstimate": null,
"timeEstimate": {
"estimate": "PT0S",
"type": "AUTO",
"resetOption": null,
"active": true
},
"workspaceId": "5b152d9b0cb8797f86cbe14f"
}
Tag
Endpoints for manipulating TAG resource
Task
Endpoints for manipulating TASK resource
Find tasks on project
If provided and true, only active tasks will be returned. Otherwise only finished tasks will be returned.
If provided, tasks will be filtered by name.
page
max page-size 5000
OK
Unauthorized
Forbidden
Not Found
Response Content-Types: */*
Response Example (200 OK)
[
{
"assigneeIds": ["593e40aab0798735d0392a2d"],
"estimate": "PT0S",
"id": "5b1e6b160cb8793dd93ec120",
"name": "Task 1",
"projectId": "5b1667790cb8797321f3d664",
"billable": "true",
"hourlyRate": {
"amount": "200",
"currency": "USD"
},
"costRate": {
"amount": "100",
"currency": "USD"
},
"status": "ACTIVE"
}
]
Find task on project by ID
OK
Unauthorized
Forbidden
Not Found
Response Content-Types: */*
Response Example (200 OK)
{
"assigneeIds": ["593e40aab0798735d0392a2d"],
"estimate": "PT0S",
"id": "5b1e6b160cb8793dd93ec120",
"name": "Task 1",
"projectId": "5b1667790cb8797321f3d664",
"billable": "true",
"hourlyRate": {
"amount": "200",
"currency": "USD"
},
"costRate": {
"amount": "100",
"currency": "USD"
},
"status": "ACTIVE"
}
Add a new task on project
Request Content-Types: application/json
Request Example
{
"name": "Task 1",
// OPTIONAL
"assigneeIds": ["593e40aab0798735d0392a2d"],
"estimate": "PT2H",
"status": "ACTIVE" (ACTIVE, DONE)
}
Created
Task with that name already exists on project, or specified project doesn't exist
Unauthorized
Forbidden
Not Found
Response Content-Types: */*
Response Example (201 Created)
{
"assigneeIds": ["593e40aab0798735d0392a2d"],
"estimate": "PT2H",
"id": "5b1e6b160cb8793dd93ec120",
"name": "Task 1",
"projectId": "5b1667790cb8797321f3d664",
"billable": "true",
"hourlyRate": {
"amount": null,
"currency": "USD"
},
"costRate": {
"amount": null,
"currency": "USD"
},
"status": "ACTIVE"
}
Update task on project
Request Content-Types: application/json
Request Example
{
"name": "Task 1",
"assigneeIds": ["593e40aab0798735d0392a2d"],
"estimate": "PT2H",
"billable": "true",
"status": "DONE"
}
Created
Task with that name already exists on project, or specified project doesn't exist
Unauthorized
Forbidden
Not Found
Response Content-Types: */*
Response Example (201 Created)
{
"assigneeIds": ["593e40aab0798735d0392a2d"],
"estimate": "PT2H",
"id": "5b1e6b160cb8793dd93ec120",
"name": "Task 1",
"projectId": "5b1667790cb8797321f3d664",
"billable": "true",
"hourlyRate": {
"amount": "200",
"currency": "USD"
},
"costRate": {
"amount": "100",
"currency": "USD"
},
"status": "DONE"
}
Delete task from project
OK
No Content
Project with specified id not found
Unauthorized
Forbidden
Response Content-Types: */*
Response Example (200 OK)
{
"assigneeIds": ["593e40aab0798735d0392a2d"],
"estimate": "PT2H",
"id": "5b1e6b160cb8793dd93ec120",
"name": "Task 1",
"projectId": "5b1667790cb8797321f3d664",
"billable": "true",
"hourlyRate": {
"amount": "200",
"currency": "USD"
},
"costRate": {
"amount": "100",
"currency": "USD"
},
"status": "DONE"
}
Time entry
Endpoints for manipulating TIMEENTRY resource
Get your time entries on workspace
Gets a time entry for specified user on workspace. Filters can be applied as query parameters listed below
Requires WORKSPACE_OWN or WORKSPACE_ADMIN permissions to see other user's time entries.
If provided, time entries will be filtered by description.
If provided, only time entries that started after the specified datetime will be returned. Datetime must be in ISO-8601 format (eg. "2019-04-16T05:15:32.998Z"). You send time according to your account's timezone (from Profile Settings) and get response with time in UTC.
If provided, only time entries that started before the specified datetime will be returned. Datetime must be in ISO-8601 format (eg. 2019-04-16T05:15:32.998Z"). You send time according to your account's timezone (from Profile Settings) and get response with time in UTC.
If provided, time entries will be filtered by project.
If provided, time entries will be filtered by task.
If provided, time entries will be filtered by tags. This parameter is an array of tag ids.
?tags=tagId_1&tags=tagId_2 If provided, only time entries with project will be returned.
If provided, only time entries with task will be returned.
If provided, returned timeentry's duration will be rounded to minutes or seconds based on duration format (hh:mm or hh:mm:ss) from workspace settings.
If provided, returned timeentry's project,task and tags will be returned in full and not just their ids. Note that if you request hydrated entity version, projectId, taskId and tagIds will be changed to project, task and tags in request response.
If provided, all other filters will be ignored and, if present, currently running time entry will be returned.
page
max page-size 5000
OK
User with given ID doesn't exist
Unauthorized
Forbidden
Not Found
Response Content-Types: */*
Response Example (200 OK)
[
{
"billable": "true",
"description": "Writing documentation",
"id": "5b0fdf2a0cb87904845dfer5",
"isLocked": "false",
"projectId": "5b1667790cb8797321f3d664",
"tagIds": [
"5a7c5d2db079870147fra234"
],
"taskId": "5b1e6b160cb8793dd93ec120",
"timeInterval": {
"duration": "PT1M4S",
"end": "2018-06-12T14:01:41Z",
"start": "2018-06-12T14:00:37Z"
},
"userId": "6h1e49bf0cb8790e43d6c9ab",
"workspaceId": "5g3g57bt0cb2548e22e6l9cd"
},
"customFieldValues": [
{
"customFieldId" : "5b1e6b160cb8793dd93ec120",
"timeEntryId" : "5c5bda4fb079871c518b6f07",
"value": "San Francisco",
"name": "Location",
"type": "TXT"
}
]
]
Get a specific time entry on workspace
If provided, returned timeentry's duration will be rounded to minutes or seconds based on duration format (hh:mm or hh:mm:ss) from workspace settings.
If provided, returned timeentry's project,task and tags will be returned in full and not just their ids. Note that if you request hydrated entity version, projectId, taskId and tagIds will be changed to project, task and tags in request response.
OK
Time entry with given ID doesn't exist
Unauthorized
Forbidden
Not Found
Response Content-Types: */*
Response Example (200 OK)
{
"billable": "true",
"description": "Writing documentation",
"id": "5b0fdf2a0cb87904845dfer5",
"isLocked": "false",
"projectId": "5b1667790cb8797321f3d664",
"tagIds": [
"5a7c5d2db079870147fra234"
],
"taskId": "5b1e6b160cb8793dd93ec120",
"timeInterval": {
"duration": "PT2M",
"end": "2018-06-12T13:50:14Z",
"start": "2018-06-12T13:48:14Z"
},
"userId": "6h1e49bf0cb8790e43d6c9ab",
"workspaceId": "5g3g57bt0cb2548e22e6l9cd",
"customFieldValues": [
{
"customFieldId" : "5b1e6b160cb8793dd93ec120",
"timeEntryId" : "5c5bda4fb079871c518b6f07",
"value": "San Francisco",
"name": "Location",
"type": "TXT"
}
]
}
Add a new time entry to workspace
If end is not sent in request means that stopwatch mode is active, otherwise time entry is manually added.
'start' is the only mandatory field in this request.
Request Content-Types: application/json
Request Example
{
"start": "2018-06-12T13:48:14.000Z",
"billable": "true",
"description": "Writing documentation",
"projectId": "5b1667790cb8797321f3d664",
"taskId": "5b1e6b160cb8793dd93ec120",
"end": "2018-06-12T13:50:14.000Z",
"tagIds": [
"5a7c5d2db079870147fra234"
],
"customFields": [
{
"customFieldId" : "5b1e6b160cb8793dd93ec120",
"value": "San Francisco"
}
]
}
Created
Project//Tag doesn't exist or doesn't belong to workspace; Task doesn't exist or doesn't belong to project; Start datetime is after end datetime;Time entry requires additional info (check workspace settings);
Unauthorized
Forbidden
Not Found
Response Content-Types: */*
Response Example (201 Created)
{
"billable": "true",
"description": "Writing documentation",
"id": "5b0fdf2a0cb87904845dfer5",
"isLocked": "false",
"projectId": "5b1667790cb8797321f3d664",
"tagIds": [
"5a7c5d2db079870147fra234"
],
"taskId": "5b1e6b160cb8793dd93ec120",
"timeInterval": {
"duration": "PT2M",
"end": "2018-06-12T13:48:14Z",
"start": "2018-06-12T13:50:14Z"
},
"userId": "6h1e49bf0cb8790e43d6c9ab",
"workspaceId": "5g3g57bt0cb2548e22e6l9cd",
"customFieldValues": [
{
"customFieldId" : "5b1e6b160cb8793dd93ec120",
"timeEntryId" : "5c5bda4fb079871c518b6f07",
"value": "San Francisco",
"name": "Location",
"type": "TXT"
}
]
}
Add a new time entry for another user on workspace
Adding time for others is a paid feature. This API endpoint works only for workspaces that have an active paid subscription.
You specify for which user you're adding time in the request's POST path.
If you leave out end time, you'll start a timer for that person. To stop the timer, you'll have to use the "PUT /workspaces/{workspaceId}/time-entries/{timeEntryId}/end" PATH (request example: {"end":"2019-02-07T14:00:07.000Z"}
Request Content-Types: application/json
Request Example
{
"start": "2018-06-12T13:48:14.000Z",
"billable": "true",
"description": "Writing documentation",
"projectId": "5b1667790cb8797321f3d664",
"taskId": "5b1e6b160cb8793dd93ec120",
"end": "2018-06-12T13:50:14.000Z",
"tagIds": [
"5a7c5d2db079870147fra234"
],
"customFields": [
{
"customFieldId" : "5b1e6b160cb8793dd93ec120",
"value": "San Francisco"
}
]
}
Created
Project/Tag/User doesn't exist or doesn't belong to workspace; Task doesn't exist or doesn't belong to project; Start datetime is after end datetime;Time entry requires additional info (check workspace settings)
Unauthorized
Forbidden
Not Found
Response Content-Types: */*
Response Example (201 Created)
{
"billable": "true",
"description": "Writing documentation",
"id": "5b0fdf2a0cb87904845dfer5",
"isLocked": "false",
"projectId": "5b1667790cb8797321f3d664",
"tagIds": [
"5a7c5d2db079870147fra234"
],
"taskId": "5b1e6b160cb8793dd93ec120",
"timeInterval": {
"duration": "PT2M",
"end": "2018-06-12T13:50:14Z",
"start": "2018-06-12T13:48:14Z"
},
"userId": "6h1e49bf0cb8790e43d6c9ab",
"workspaceId": "5g3g57bt0cb2548e22e6l9cd",
"customFieldValues": [
{
"customFieldId" : "5b1e6b160cb8793dd93ec120",
"timeEntryId" : "5c5bda4fb079871c518b6f07",
"value": "San Francisco",
"name": "Location",
"type": "TXT"
}
]
}
Stop currently running timer on workspace
Admins can stop someone else's running timers on paid workspaces (Add time for others feature).
If workspace has a required field enabled (eg. the Timesheet is enabled and project is a required field as a result), you won't be able to stop the timer until you fill in the required field(s). You'll simply get "Entity not created" message.
Request Content-Types: application/json
Request Example
{
"end": "2018-06-12T14:01:41Z"
}
OK
No Content
Required information is not present on currently running time entry. Check your workspace settings.
Unauthorized
Forbidden
Currently running time entry was not found on workspace
Response Content-Types: */*
Response Example (200 OK)
{
"billable": "true",
"description": "Writing documentation updated",
"id": "5b0fdf2a0cb87904845dfer5",
"isLocked": "false",
"projectId": "5b1667790cb8797321f3d664",
"tagIds": [
"5a7c5d2db079870147fra234"
],
"taskId": "5b1e6b160cb8793dd93ec120",
"timeInterval": {
"duration": "PT1M4S",
"end": "2018-06-12T14:01:41Z",
"start": "2018-06-12T14:00:37Z"
},
"userId": "6h1e49bf0cb8790e43d6c9ab",
"workspaceId": "5g3g57bt0cb2548e22e6l9cd",
"customFieldValues": [
{
"customFieldId" : "5b1e6b160cb8793dd93ec120",
"timeEntryId" : "5c5bda4fb079871c518b6f07",
"value": "San Francisco",
"name": "Location",
"type": "TXT"
}
]
}
Update time entry on workspace
Request Content-Types: application/json
Request Example
{
"start": "2018-06-12T14:00:37Z",
"billable": "true",
"description": "Writing documentation updated",
"projectId": "5b1667790cb8797321f3d664",
"taskId": "5b1e6b160cb8793dd93ec120",
"end": "2018-06-12T14:01:41Z",
"tagIds": [
"5a7c5d2db079870147fra234"
],
"customFields": [
{
"customFieldId" : "5b1e6b160cb8793dd93ec120",
"timeEntryId" : "5c5bda4fb079871c518b6f07",
"value": "San Francisco"
}
]
}
OK
Created
Project/Tag doesn't exist or doesn't belong to workspace; Task doesn't exist or doesn't belong to project; Start datetime is after end datetime
Unauthorized
Forbidden
Not Found
Response Content-Types: */*
Response Example (200 OK)
{
"billable": "true",
"description": "Writing documentatio updated",
"id": "5b0fdf2a0cb87904845dfer5",
"isLocked": "false",
"projectId": "5b1667790cb8797321f3d664",
"tagIds": [
"5a7c5d2db079870147fra234"
],
"taskId": "5b1e6b160cb8793dd93ec120",
"timeInterval": {
"duration": "PT1M4S",
"end": "2018-06-12T14:01:41Z",
"start": "2018-06-12T14:00:37Z"
},
"userId": "6h1e49bf0cb8790e43d6c9ab",
"workspaceId": "5g3g57bt0cb2548e22e6l9cd",
"customFieldValues": [
{
"customFieldId" : "5b1e6b160cb8793dd93ec120",
"timeEntryId" : "5c5bda4fb079871c518b6f07",
"value": "San Francisco",
"name": "Location",
"type": "TXT"
}
]
}
Mark time entries as invoiced
Request Content-Types: application/json
Request Example
{
"timeEntryIds": ["5a7c5d2db079870147fra134"],
"invoiced" : true
}
OK
Bad Request
Unauthorized
Forbidden
Not Found
Delete time entry from workspace
No Content
Time entry with given ID doesn't exist or doesn't belong to workspace
Unauthorized
Forbidden
Response Content-Types: */*
User
Endpoints for manipulating USER resource
Get currently logged in user's info
OK
Unauthorized
Forbidden
Not Found
Response Content-Types: */*
Response Example (200 OK)
{
"activeWorkspace": "592e9e48b0798735d03919ee",
"defaultWorkspace": "592e9e48b0798735d03919ee",
"email": "email@test.com",
"id": "5bfd36c4b0798777049512e2",
"memberships": [
{
"hourlyRate": {
"amount": "500",
"currency": "USD"
},
"costRate": {
"amount": "100",
"currency": "USD"
},
"membershipStatus": "ACTIVE",
"membershipType": "WORKSPACE",
"targetId": "5bfd36c4b0798777049512e3",
"userId": "5bfd36c4b0798777049512e2"
}
],
"name": "Username",
"profilePicture": "https://s3.eu-central-1.amazonaws.com/clockify/no-user-image.png",
"settings": {
"collapseAllProjectLists": "false",
"dashboardPinToTop": "false",
"dashboardSelection": "ME",
"dashboardViewType": "BILLABILITY",
"dateFormat": "MM/DD/YYYY",
"isCompactViewOn": "false",
"longRunning": "false",
"projectListCollapse": null,
"sendNewsletter": "false",
"summaryReportSettings": {
"group": "Project", (Group: Project, Client, User, Tag, Time Entry, Task)
"subgroup": "Time Entry" (Subgroup: Project, Client, User, Tag)
},
"timeFormat": "HOUR12",
"timeTrackingManual": "false",
"timeZone": "Europe/Belgrade",
"weekStart": "MONDAY",
"weeklyUpdates": "false"
},
"status": "ACTIVE"
}
Find all users on workspace
page
max page-size 5000
If provided, you'll get all users along with what workspace, groups, or projects they have access to. Possible values: WORKSPACE, PROJECT, USERGROUP, ALL (default), NONE (only get basic data about users on the workpace).
If provided, you'll get a filtered list of users that contain the provided string in their email address.
If provided, you'll get a list of users that have access to the project.
If provided, you'll get a filtered list of users that contain the provided string in their name.
If provided, you'll get a filtered list of users with the corresponding status. Possible values: PENDING, ACTIVE, DECLINED, INACTIVE
Possible values: EMAIL, NAME, HOURLYRATE
Possible values: ASCENDING, DESCENDING
If you pass along includeRoles=true, you'll get each user's detailed manager role (including projects and members for whome they're managers)
?email=@gmail&memberships=NONE&page-size=100&status=ACTIVE OK
Unauthorized
Forbidden
Not Found
Response Content-Types: */*
Response Example (200 OK)
[
{
"activeWorkspace": "592e9e48b0798735d03919ee",
"defaultWorkspace": "592e9e48b0798735d03919ee",
"email": "email@test.com",
"id": "5bfd36c4b0798777049512e2",
"memberships": [
{
"hourlyRate": {
"amount": "500",
"currency": "USD"
},
"costRate": {
"amount": "100",
"currency": "USD"
},
"membershipStatus": "ACTIVE",
"membershipType": "WORKSPACE",
"targetId": "5bfd36c4b0798777049512e3",
"userId": "5bfd36c4b0798777049512e2"
}
],
"name": "Username",
"profilePicture": "https://s3.eu-central-1.amazonaws.com/clockify/no-user-image.png",
"settings": {
"collapseAllProjectLists": "false",
"dashboardPinToTop": "false",
"dashboardSelection": "ME",
"dashboardViewType": "BILLABILITY",
"dateFormat": "MM/DD/YYYY",
"isCompactViewOn": "false",
"longRunning": "false",
"projectListCollapse": null,
"sendNewsletter": "false",
"summaryReportSettings": {
"group": "Project", (Group: Project, Client, User, Tag, Time Entry, Task)
"subgroup": "Time Entry" (Subgroup: Project, Client, User, Tag)
},
"timeFormat": "HOUR12",
"timeTrackingManual": "false",
"timeZone": "Europe/Belgrade",
"weekStart": "MONDAY",
"weeklyUpdates": "false"
},
"status": "ACTIVE",
"roles": [
{
"role": "PROJECT_MANAGER",
"entities": [
{
"id": "5f8ec3833f2109522c00966a",
"name": "My project 1"
}
]
},
{
"role": TEAM_MANAGER",
"entities": [
{
"id": "6g8ec3833f2109522c00966a",
"name": "Mary Smith"
}
]
}
]
}
]
Add user to workspace
You can add users to a workspace via API only if that workspace has a paid subscription. If the workspace has a paid subscription, you can add as many users as you want but you are limited by the number of paid user seats on that workspace.
Request Content-Types: application/json
Request Example
{
"email": "example@email.com"
}
OK
Created
Bad Request
Unauthorized
Forbidden
Not found
Response Content-Types: */*
Response Example (200 OK)
{
"id": "5g3g57bt0cb2548e22e6l9cd",
"imageUrl": "string",
"memberships": [
{
"hourlyRate": {
"amount": 15
},
"costRate": {
"amount": null
},
"membershipStatus": "ACTIVE",
"membershipType": "WORKSPACE",
"targetId": "5g3g57bt0cb2548e22e6l9cd",
"userId": "5h1e49bf0cb8790e43d6c9ab"
}
],
"name": "Clockify workspace",
"workspaceSettings": {
"adminOnlyPages": [
"string"
],
"automaticLock": {
"changeDay": "WEDNESDAY",
"dayOfMonth": 13,
"firstDay": "SATURDAY",
"olderThanPeriod": "DAYS",
"olderThanValue": 14,
"type": "OLDER_THAN"
},
"canSeeTimeSheet": true,
"canSeeTracker": true,
"defaultBillableProjects": true,
"forceDescription": true,
"forceProjects": true,
"forceTags": true,
"forceTasks": true,
"isProjectPublicByDefault": "false",
"lockTimeEntries": "2019-01-31T23:00:00Z",
"onlyAdminsCreateProject": true,
"onlyAdminsCreateTag": "false",
"onlyAdminsCreateTask": true,
"onlyAdminsSeeAllTimeEntries": true,
"onlyAdminsSeeBillableRates": true,
"onlyAdminsSeeDashboard": true,
"onlyAdminsSeePublicProjectsEntries": true,
"projectFavorites": true,
"projectGroupingLabel": "Department",
"projectPickerSpecialFilter": true,
"round": {
"minutes": 15,
"round": "Round up to"
},
"timeRoundingInReports": true,
"trackTimeDownToSecond": true
}
}
Update user's workspace status
Request Content-Types: application/json
Request Example
{
"membershipStatus": "INACTIVE" (ACTIVE, INACTIVE)
}
OK
Created
Bad Request
Unauthorized
Forbidden
Not found
Response Content-Types: */*
Response Example (200 OK)
{
"id": "5g3g57bt0cb2548e22e6l9cd",
"imageUrl": "string",
"memberships": [
{
"hourlyRate": {
"amount": 15
},
"costRate": {
"amount": "100"
},
"membershipStatus": "ACTIVE",
"membershipType": "WORKSPACE",
"targetId": "5g3g57bt0cb2548e22e6l9cd",
"userId": "5h1e49bf0cb8790e43d6c9ab"
}
],
"name": "Clockify workspace",
"workspaceSettings": {
"adminOnlyPages": [
"string"
],
"automaticLock": {
"changeDay": "WEDNESDAY",
"dayOfMonth": 13,
"firstDay": "SATURDAY",
"olderThanPeriod": "DAYS",
"olderThanValue": 14,
"type": "OLDER_THAN"
},
"canSeeTimeSheet": true,
"canSeeTracker": true,
"defaultBillableProjects": true,
"forceDescription": true,
"forceProjects": true,
"forceTags": true,
"forceTasks": true,
"isProjectPublicByDefault": "false",
"lockTimeEntries": "2019-01-31T23:00:00Z",
"onlyAdminsCreateProject": true,
"onlyAdminsCreateTag": "false",
"onlyAdminsCreateTask": true,
"onlyAdminsSeeAllTimeEntries": true,
"onlyAdminsSeeBillableRates": true,
"onlyAdminsSeeDashboard": true,
"onlyAdminsSeePublicProjectsEntries": true,
"projectFavorites": true,
"projectGroupingLabel": "Department",
"projectPickerSpecialFilter": true,
"round": {
"minutes": 15,
"round": "Round up to"
},
"timeRoundingInReports": true,
"trackTimeDownToSecond": true
}
}
Remove user from workspace
OK
No Content
Bad Request
Unauthorized
Forbidden
Not found
Response Content-Types: */*
Group
Endpoints for manipulating group resource
Find all groups on workspace
page
max page-size 5000
projectId
name
ASCENDING, DESCENDING
NAME
OK
Unauthorized
Forbidden
Not Found
Response Content-Types: */*
Response Example (200 OK)
[
{
"id": "5a0b0c2c307987125438b903",
"name": "Admins",
"workspaceId": "5a0b01dcb07987125438b902",
"userIds": [
"5a0ab5acb07987125438b60f",
"599b90jnb0798723decee4f0",
"5a1d311db079872b2a7b5a2f"
]
}
]
Add a new group to workspace
Request Content-Types: application/json
Request Example
{
"name": "My group"
}
Created
Tag with that name already exists on workspace
Unauthorized
Forbidden
Not Found
Response Content-Types: */*
Response Example (201 Created)
{
"id": "5a7c5d2d2079870147fra234",
"name": "My group",
"workspaceId": "5g3g57bt0cb2548e22e6l9cd"
}
Update group name
Request Content-Types: application/json
Request Example
{
"name": "Group"
}
OK
Created
Bad Request
Unauthorized
Forbidden
Not found
Response Content-Types: */*
Response Example (200 OK)
{
"id": "5bf6d2b9b079876a34621638",
"name": "Group",
"userIds": [
"string"
],
"workspaceId": "5bfd36c4b0798777049512e3"
}
Delete group
OK
No Content
Bad Request
Unauthorized
Forbidden
Not found
Response Content-Types: */*
Response Example (200 OK)
{
"id": "5bf6d2b9b079876a34621638",
"name": "Group",
"userIds": [
"5b23d2b9b079876a34621638"
],
"workspaceId": "5bfd36c4b0798777049512e3"
}
Add users to group
Request Content-Types: application/json
Request Example
{
"userId": "5bf6d2b9b079876a34621635"
}
OK
Created
Bad Request
Unauthorized
Forbidden
Not found
Response Content-Types: */*
Response Example (200 OK)
{
"id": "5bf6d2b9b079876a34621638",
"name": "Group",
"userIds": [
"5b23d2b9b079876a34621638"
],
"workspaceId": "5bfd36c4b0798777049512e3"
}
Remove user from group
OK
No Content
Bad Request
Unauthorized
Forbidden
Not found
Response Content-Types: */*
Response Example (200 OK)
{
"id": "5bf6d2b9b079876a34621638",
"name": "Group",
"userIds": [
"5b23d2b9b079876a34621638"
],
"workspaceId": "5bfd36c4b0798777049512e3"
}
Workspace
Endpoints for manipulating WORKSPACE resource
Get all my workspaces
OK
Unauthorized
Forbidden
Not Found
Response Content-Types: */*
Response Example (200 OK)
[
{
"hourlyRate": {
"amount": "0",
"currency": "USD"
},
"id": "5g3g57bt0cb2548e22e6l9cd",
"imageUrl": "https://s3.eu-central-1.amazonaws.com/test/workspaceImg.png",
"memberships": [
{
"hourlyRate": {
"amount": "15",
"currency": "USD"
},
"membershipStatus": "ACTIVE",
"membershipType": "WORKSPACE",
"targetId": "5g3g57bt0cb2548e22e6l9cd",
"userId": "6h1e49bf0cb8790e43d6c9ab"
}
],
"name": "Clockify workspace",
"workspaceSettings": {
"adminOnlyPages": [],
"automaticLock": {
"changeDay": "WEDNESDAY",
"dayOfMonth": "13",
"firstDay": "MONDAY",
"olderThanPeriod": "DAYS",
"olderThanValue": "14",
"type": "OLDER_THAN"
},
"canSeeTimeSheet": "false",
"canSeeTracker": "true",
"defaultBillableProjects": "true",
"forceDescription": "true",
"forceProjects": "true",
"forceTags": "false",
"forceTasks": "false",
"lockTimeEntries": "2019-01-31T23:00:00Z",
"onlyAdminsCreateProject": "false",
"onlyAdminsCreateTag": "false",
"onlyAdminsCreateTask": "true",
"onlyAdminsSeeAllTimeEntries": "true",
"onlyAdminsSeeBillableRates": "false",
"onlyAdminsSeeDashboard": "false",
"onlyAdminsSeePublicProjectsEntries": "false",
"projectFavorites": "true",
"projectGroupingLabel": "client",
"projectPickerSpecialFilter": "false",
"round": {
"minutes": "15",
"round": "Round up to"
},
"timeRoundingInReports": "true",
"trackTimeDownToSecond": "false",
"isProjectPublicByDefault": "false",
"canSeeTracker": "false",
"featureSubscriptionType": "ENTERPRISE_YEAR"
}
]
Custom fields
Endpoints for manipulating CUSTOM FIELDS resource. For managing custom fields on time entries, use endpoints for manipulating TIMEENTRY resource.
Get custom fields on workspace
INACTIVE, VISIBLE, INVISIBLE
OK
Doesn't exist
Unauthorized
Forbidden
Not Found
Response Content-Types: */*
Response Example (200 OK)
[
{
"id": "kn0fdf2a0cb87904845dfer5",
"workspaceId": "5b0fdf2a0cb87904845dfer5",
"name": "Location",
"description": "Location where the work happened.",
"type": "DROPDOWN_SINGLE", (TXT, NUMBER, DROPDOWN_SINGLE, DROPDOWN_MULTIPLE, CHECKBOX, LINK)
"placeholder": "Choose location...",
"allowedValues": [
"San Francisco",
"Beijing",
"Paris"
],
"workspaceDefaultValue": "San Francisco",
"onlyAdminCanEdit": "true",
"status": "INACTIVE", (INACTIVE, VISIBLE, INVISIBLE)
"projectDefaultValues": [
{
"projectId : "450fdf2a0cb87904845dfer5",
"value : "Beijing",
"status : "VISIBLE" (INACTIVE, VISIBLE, INVISIBLE)
}
]
}
]
Get custom fields on project
INACTIVE, VISIBLE, INVISIBLE
OK
Doesn't exist
Unauthorized
Forbidden
Not Found
Response Content-Types: */*
Response Example (200 OK)
[
{
"id": "kn0fdf2a0cb87904845dfer5",
"workspaceId": "5b0fdf2a0cb87904845dfer5",
"name": "Location",
"description": "Location where the work happened.",
"type": "DROPDOWN_SINGLE", (TXT, NUMBER, DROPDOWN_SINGLE, DROPDOWN_MULTIPLE, CHECKBOX, LINK)
"placeholder": "Choose location...",
"allowedValues": [
"San Francisco",
"Beijing",
"Paris"
],
"workspaceDefaultValue": "San Francisco",
"onlyAdminCanEdit": "true",
"status": "INACTIVE", (INACTIVE, VISIBLE, INVISIBLE)
"projectDefaultValues": [
{
"projectId : "450fdf2a0cb87904845dfer5",
"value : "Beijing",
"status : "VISIBLE" (INACTIVE, VISIBLE, INVISIBLE)
}
]
}
]
Update custom field on project
Request Content-Types: application/json
Request Example
{
"defaultValue" : "San Francisco",
"status" : "INVISIBLE" (INACTIVE, VISIBLE, INVISIBLE)
}
Success
Task with that name already exists on project, or specified project doesn't exist
Unauthorized
Forbidden
Not Found
Response Content-Types: */*
Response Example (201 Success)
{
"id": "kn0fdf2a0cb87904845dfer5",
"workspaceId": "5b0fdf2a0cb87904845dfer5",
"name": "Location",
"description": "Location where the work happened.",
"type": "DROPDOWN_SINGLE", (TXT, NUMBER, DROPDOWN_SINGLE, DROPDOWN_MULTIPLE, CHECKBOX, LINK)
"placeholder": "Choose location...",
"allowedValues": [
"San Francisco",
"Beijing",
"Paris"
],
"workspaceDefaultValue": "San Francisco",
"onlyAdminCanEdit": "true",
"status": "INACTIVE", (INACTIVE, VISIBLE, INVISIBLE)
"projectDefaultValues": [
{
"projectId : "450fdf2a0cb87904845dfer5",
"value : "San Francisco",
"status : "INVISIBLE" (INACTIVE, VISIBLE, INVISIBLE)
}
]
}
Remove custom field from project
OK
Doesn't exist
Unauthorized
Forbidden
Not Found
Response Content-Types: */*
Response Example (200 OK)
{
"id": "kn0fdf2a0cb87904845dfer5",
"workspaceId": "5b0fdf2a0cb87904845dfer5",
"name": "Location",
"description": "Location where the work happened.",
"type": "DROPDOWN_SINGLE", (TXT, NUMBER, DROPDOWN_SINGLE, DROPDOWN_MULTIPLE, CHECKBOX, LINK)
"placeholder": "Choose location...",
"allowedValues": [
"San Francisco",
"Beijing",
"Paris"
],
"workspaceDefaultValue": "San Francisco",
"onlyAdminCanEdit": "true",
"status": "INACTIVE", (INACTIVE, VISIBLE, INVISIBLE)
"projectDefaultValues": []
}
Reports
Endpoints for manipulating REPORTS resource.
To get a report in a different format, you need to specify it in the exportType for each POST request (possible values: JSON, CSV, XLSX, PDF).
API Base Endpoint for Reports
https://reports.api.clockify.me/v1Summary report
Possible values: PROJECT, CLIENT, TASK, TAG, DATE, USER, USER_GROUP, TIMEENTRY
Possible values: INVOICED, UNINVOICED, ALL
Possible values: APPROVED, UNAPPROVED, ALL
Possible values: GROUP, DURATION, AMOUNT
Possible values: HIDE_AMOUNT, EARNED, COST, PROFIT
Possible values: JSON, CSV, XLSX, PDF
Possible values: ASCENDING, DESCENDING
CONTAINS, DOES_NOT_CONTAIN
CONTAINS, CONTAINS_ONLY, DOES_NOT_CONTAIN
Projects, clients, tags: ALL, ACTIVE, ARCHIVED
Users: ALL, ACTIVE, INACTIVE
Tasks: ALL, ACTIVE, DONE
If you don't include timeZone, time zone from your profile settings will be used for request and response. If you include timeZone, you send and receive times according to the time zone you've specified.
Request Content-Types: application/json
Request Example
{
// REQUIRED
"dateRangeStart": "2020-05-10T00:00:00.000",
"dateRangeEnd": "2020-05-16T23:59:59.000",
"summaryFilter": {
"groups": [
"USER",
"PROJECT",
"TIMEENTRY"
],
// SETTINGS (OPTIONAL)
"sortColumn": "GROUP"
},
"sortOrder": "DESCENDING",
"exportType": "JSON",
"rounding": false,
"amountShown": "EARNED",
"timeZone": "America/Los_Angeles",
// FILTERS (OPTIONAL)
"users": {
"ids": ["45fd36c4b0798777049512e2"],
"contains": "CONTAINS",
"status": "ALL"
},
"invoicingState": "ALL",
"approvalState": "ALL",
"userGroups": null,
"clients": null,
"projects": null,
"tasks": null,
"tags": {
"ids": ["45fd36c4b0798777049512e2"],
"containedInTimeentry": "DOES_NOT_CONTAIN",
"status": "ALL"
},
"billable": true,
"description": "",
"withoutDescription": true,
"customFields": [
{
"id": "5bfd36c4b0798777049512e2",
"value": 30,
"type": "NUMBER"
"numberCondition": "EQUAL"
"empty": "false"
}
]
}
Bad Request
Unauthorized
Forbidden
Not found
Response Content-Types: application/json
Request Example
{
"totals": [
{
"totalTime": 3600,
"totalBillableTime": 3600,
"entriesCount": 1,
"totalAmount": 750.00
}
],
"groupOne": [
{
"_id": "5bfd36c4b0798777049512e2",
"duration": 3600,
"amount": 750.00,
"name": "User"
"children": [
"_id": "2020-05-15",
"duration": 3600,
"amount": 750.00,
"name": "2020-05-15",
"children": [
"_id": "5eb9244d5440c74ec17850db",
"duration": 3600,
"amount": 750.00,
"name": "My entry description",
]
]
}
]
}
Detailed report
Possible values: ID, DESCRIPTION, USER, DURATION, DATE
Possible values: INVOICED, UNINVOICED, ALL
Possible values: APPROVED, UNAPPROVED, ALL
Possible values: HIDE_AMOUNT, EARNED, COST, PROFIT
Possible values: JSON, CSV, XLSX, PDF
Possible values: GROUP, DURATION, AMOUNT
Possible values: ASCENDING, DESCENDING
CONTAINS, DOES_NOT_CONTAIN
CONTAINS, CONTAINS_ONLY, DOES_NOT_CONTAIN
Projects, clients, tags: ALL, ACTIVE, ARCHIVED
Users: ALL, ACTIVE, INACTIVE
Tasks: ALL, ACTIVE, DONE
Max value: 1000
If you send CALCULATE option, you'll get the response with "totals". For better performance and to generate the report more quickly, it's best to use EXCLUDE option.
If you don't include timeZone, time zone from your profile settings will be used for request and response. If you include timeZone, you send and receive times according to the time zone you've specified.
Request Content-Types: application/json
Request Example
{
// REQUIRED
"dateRangeStart": "2020-05-10T00:00:00.000",
"dateRangeEnd": "2020-05-16T23:59:59.000",
"detailedFilter": {
"page": 1,
"pageSize": 50,
// SETTINGS (OPTIONAL)
"sortColumn": "DATE",
"options": {
"totals": "EXCLUDE"
},
"auditFilter": {
"withoutProject": true,
"withoutTask": true,
"duration": 3600,
"durationShorter": true
}
},
"sortOrder": "DESCENDING",
"exportType": "JSON",
"rounding": false,
"amountShown": "EARNED",
"timeZone": "America/Los_Angeles",
// FILTERS (OPTIONAL)
"users": {
"ids": ["45fd36c4b0798777049512e2"],
"contains": "CONTAINS",
"status": "ALL"
},
"invoicingState": "ALL",
"approvalState": "ALL",
"userGroups": null,
"clients": null,
"projects": null,
"tasks": null,
"tags": {
"ids": ["45fd36c4b0798777049512e2"],
"containedInTimeentry": "DOES_NOT_CONTAIN",
"status": "ALL"
},
"billable": true,
"description": "",
"withoutDescription": true,
"customFields": [
{
"id": "5bfd36c4b0798777049512e2",
"value": 30,
"type": "NUMBER"
"numberCondition": "EQUAL"
"empty": "false"
}
]
}
Bad Request
Unauthorized
Forbidden
Not found
Response Content-Types: application/json
Request Example
{
"totals": [
{
"totalTime": 3600,
"totalBillableTime": 3600,
"entriesCount": 1,
"totalAmount": 750.00
}
],
"timeentries": [
{
"_id": "5e56518286d6ae2aface01fc",
"description": "My entry description",
"userId": "5bfd36c4b0798777049512e2",
"billable": true,
"taskId": null,
"projectId": null,
"clientId": null,
"timeInterval": {
"start": "2020-05-15T08:00:00+02:00",
"end": "2020-05-15T09:00:00+02:00",
"duration": 3600,
},
"approvalRequestId": "5ff589bbaedbbe170a50b033",
"taskName": "Development",
"tags": [],
"isLocked": false,
"customFields": [
{
"customFieldId": "5e58e3ad00352a1175baec69",
"value": "500"
}
],
"invoicingInfo": {
"invoiceId": "5ff2dde14c738333e1bd5d36",
"invoiceNumber": "INV-001",
"manuallyInvoiced": false
},
"amount": 750.00,
"rate": 750.00,
"userName": "James White",
"userEmail": "james@acme.com",
"projectName": "ProjectX",
"projectColor": "#8BC34A",
"clientName": "ClientX"
}
]
}
Weekly report
Possible values: PROJECT, USER
Possible values: INVOICED, UNINVOICED, ALL
Possible values: APPROVED, UNAPPROVED, ALL
Possible values: TIME, EARNED
Possible values: HIDE_AMOUNT, EARNED, COST, PROFIT
Possible values: JSON, CSV, XLSX, PDF
Possible values: GROUP, DURATION, AMOUNT
Possible values: ASCENDING, DESCENDING
CONTAINS, DOES_NOT_CONTAIN
CONTAINS, CONTAINS_ONLY, DOES_NOT_CONTAIN
Projects, clients, tags: ALL, ACTIVE, ARCHIVED
Users: ALL, ACTIVE, INACTIVE
Tasks: ALL, ACTIVE, DONE
If you don't include timeZone, time zone from your profile settings will be used for request and response. If you include timeZone, you send and receive times according to the time zone you've specified.
Request Content-Types: application/json
Request Example
{
// REQUIRED
"dateRangeStart": "2020-05-10T00:00:00.000",
"dateRangeEnd": "2020-05-16T23:59:59.000",
"weeklyFilter": {
"group": "USER",
"subgroup": "TIME"
},
// SETTINGS (OPTIONAL)
"sortOrder": "DESCENDING",
"exportType": "JSON",
"rounding": false,
"amountShown": "EARNED",
"timeZone": "America/Los_Angeles",
// FILTERS (OPTIONAL)
"users": {
"ids": ["45fd36c4b0798777049512e2"],
"contains": "CONTAINS",
"status": "ALL"
},
"userGroups": null,
"invoicingState": "ALL",
"approvalState": "ALL",
"clients": null,
"projects": null,
"tasks": null,
"tags": {
"ids": ["45fd36c4b0798777049512e2"],
"containedInTimeentry": "DOES_NOT_CONTAIN",
"status": "ALL"
},
"billable": true,
"description": "",
"withoutDescription": true,
"customFields": [
{
"id": "5bfd36c4b0798777049512e2",
"value": 30,
"type": "NUMBER"
"numberCondition": "EQUAL"
"empty": "false"
}
]
}
Bad Request
Unauthorized
Forbidden
Not found
Response Content-Types: application/json
Request Example
{
"totals": [
{
"totalTime": 3600,
"totalBillableTime": 3600,
"entriesCount": 1,
"totalAmount": 750.00
}
],
"totalsByDay": [
{
"amount": 0.00,
"duration": 0.00,
"date": "2020-05-11"
},
{
"amount": 0.00,
"duration": 0.00,
"date": "2020-05-12"
},
{
"amount": 0.00,
"duration": 0.00,
"date": "2020-05-13"
},
{
"amount": 0.00,
"duration": 0.00,
"date": "2020-05-14"
},
{
"amount": 750.00,
"duration": 3600,
"date": "2020-05-15"
},
{
"amount": 0.00,
"duration": 0.00,
"date": "2020-05-16"
},
{
"amount": 0.00,
"duration": 0.00,
"date": "2020-05-17"
}
],
"groupOne": [
{
"_id": "5bfd36c4b0798777049512e2",
"duration": 3600,
"amount": 750.00,
"name": "User"
"days": [
{
"amount": 0.00,
"duration": 0.00,
"date": "2020-05-11"
},
{
"amount": 0.00,
"duration": 0.00,
"date": "2020-05-12"
},
{
"amount": 0.00,
"duration": 0.00,
"date": "2020-05-13"
},
{
"amount": 0.00,
"duration": 0.00,
"date": "2020-05-14"
},
{
"amount": 750.00,
"duration": 3600,
"date": "2020-05-15"
},
{
"amount": 0.00,
"duration": 0.00,
"date": "2020-05-16"
},
{
"amount": 0.00,
"duration": 0.00,
"date": "2020-05-17"
}
],
"children": [
"_id": "5d308a73abad777bfa652291",
"duration": 3600,
"amount": 750.00,
"name": "Project",
"color": "#F44336",
"clientName": "Client",
"days": [
{
"amount": 0.00,
"duration": 0.00,
"date": "2020-05-11"
},
{
"amount": 0.00,
"duration": 0.00,
"date": "2020-05-12"
},
{
"amount": 0.00,
"duration": 0.00,
"date": "2020-05-13"
},
{
"amount": 0.00,
"duration": 0.00,
"date": "2020-05-14"
},
{
"amount": 750.00,
"duration": 3600,
"date": "2020-05-15"
},
{
"amount": 0.00,
"duration": 0.00,
"date": "2020-05-16"
},
{
"amount": 0.00,
"duration": 0.00,
"date": "2020-05-17"
}
]
]
}
]
}
Shared reports
Endpoints for manipulating SHARED REPORTS resource.
Need to use API Base Endpoint for Reports.
API Base Endpoint for Reports
https://reports.api.clockify.me/v1