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
Dec 23, 2020
- New header parameter "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)
Nov 9, 2020
- Added timeZone paramater for reports
- Shared reports are now saved with timeFormat, dateFormat, weekStart
Aug 28, 2020
- New endpoint: GET Custom fields on projects
- New endpoint: UPDATE Custom fields on project
- New endpoint: REMOVE Custom fields from project
- New webhook event types: Me/Anyone
Jul 9, 2020
- Request update: UPDATE Time entry can take customFields
- New endpoint: GET Custom fields
- New endpoint: GET Shared reports
- New endpoint: CREATE Shared report
- New endpoint: UPDATE Shared report
- New endpoint: DELETE Shared report
- New endpoint: GENERATE Shared report
- New endpoint: UPDATE Project memberships
Jul 2, 2020
- Request update: UPDATE Project can take hourlyRate
- New endpoint: UPDATE Tag
- New endpoint: DELETE Tag
- New endpoint: UPDATE Client
- New endpoint: DELETE Client
- New endpoint: ADD Workspace user
- New endpoint: DELETE Workspace user
- New endpoint: UPDATE Workspace user's status
- New endpoint: CREATE Group
- New endpoint: DELETE Group
- New endpoint: UPDATE Group name
- New endpoint: ADD User to group
- New endpoint: DELETE User from group
Jun 17, 2020
- New endpoint: POST Summary report
- New endpoint: POST Detailed report
- New endpoint: POST Weekly report
Apr 22, 2020
- New endpoint: GET Project by ID
- New endpoint: UPDATE Project
- New endpoint: UPDATE Project template
- New endpoint: GET Task by ID
- New endpoint: UPDATE Task
- New endpoint: DELETE Task
- New endpoint: GET Time entry by ID
- New endpoint: GET Groups
- New parameters: GET Clients can now have sort-column and sort-order
- New parameters: GET Tags can now have sort-column, sort-order
- New parameters: GET Users can now have sort-column, sort-order
- New parameters: GET Projects can now have billable, clients, contains-client, users, contains-users, is-template, sort-column, sort-order
- Request update: CREATE Time entry can now have customFields; it no longers has userId, timeInterval, workspaceId, isLocked
- Response update: GET Time entries now also returns customFieldValues
- Response update: GET Projects now also returns note, template
- Response update: GET Clients now also returns archived
- Response update: GET Tags now also returns archived
- Response update: GET Tags now also returns archived
- Response update: GET Workspace now also returns isProjectPublicByDefault, canSeeTracker, featureSubscriptionType
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. You can access webhooks from the bottom of your Profile settings
Only workspace admins can create webhooks. Only the user who created the webhook can see and modify it. Each user can have up to 10 webhooks per workspace, and a workspace can have 100 in total
You can see logs of sent webhooks by clicking on a webhook you've created. There you can 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.
You can send "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 "Action-Metadata: MyRequestId123" in the header, and when the "time entry updated" webhook is triggered, you'll receive "Action-Metadata: MyRequestId123" in the webhook so you can avoid endless update loop.
To test and debug webhooks, you can use an online service like Request Catcher.
Available webhooks in Clockify
- Timer started/stopped (me/anyone)
- Time entry created manually/updated/deleted (me/anyone)
- Client/project/task/tag created on workspace
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
page-size
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
page-size
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",
"estimate": {
"estimate": "PT1H0M0S",
"type": "MANUAL"
}, // Legacy field, same info as timeEstimate
"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
page-size
OK
Unauthorized
Forbidden
Not Found
Response Content-Types: */*
Response Example (200 OK)
[
{
"assigneeIds": ["593e40aab0798735d0392a2d"],
"estimate": "PT0S",
"id": "5b1e6b160cb8793dd93ec120",
"name": "Task 1",
"projectId": "5b1667790cb8797321f3d664",
"status": "ACTIVE" (Status: ACTIVE, DONE)
}
]
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",
"status": "ACTIVE" (Status: ACTIVE, DONE)
}
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",
"status": "ACTIVE"
}
Update task on project
Request Content-Types: application/json
Request Example
{
"name": "Task 1",
"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",
"status": "ACTIVE"
}
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",
"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 both send and get time based on 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 both send and get time based on 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
page-size
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"
},
"customFields": [
{
"customFieldId" : "5b1e6b160cb8793dd93ec120",
"timeEntryId" : "5c5bda4fb079871c518b6f07",
"value": "San Francisco",
"name": "Location"
}
]
]
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",
"customFields": [
{
"customFieldId" : "5b1e6b160cb8793dd93ec120",
"timeEntryId" : "5c5bda4fb079871c518b6f07",
"value": "San Francisco",
"name": "Location"
}
]
}
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",
"customFields": [
{
"customFieldId" : "5b1e6b160cb8793dd93ec120",
"timeEntryId" : "5c5bda4fb079871c518b6f07",
"value": "San Francisco",
"name": "Location"
}
]
}
Add a new time entry for another user on workspace
Adding time for others is a premium feature. This API endpoint works only for workspaces with active Premium 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",
"customFields": [
{
"customFieldId" : "5b1e6b160cb8793dd93ec120",
"timeEntryId" : "5c5bda4fb079871c518b6f07",
"value": "San Francisco",
"name": "Location"
}
]
}
Stop currently running timer on workspace
Admins can stop someone else's running timers on Premium 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",
"customFields": [
{
"customFieldId" : "5b1e6b160cb8793dd93ec120",
"timeEntryId" : "5c5bda4fb079871c518b6f07",
"value": "San Francisco",
"name": "Location"
}
]
}
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",
"name": "Location"
}
]
}
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",
"customFields": [
{
"customFieldId" : "5b1e6b160cb8793dd93ec120",
"timeEntryId" : "5c5bda4fb079871c518b6f07",
"value": "San Francisco",
"name": "Location"
}
]
}
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"
},
"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
page-size
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
?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"
},
"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"
}
]
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 PLUS or PREMIUM subscription, you can add as many users as you want. If the workspace has ENTERPRISE subscription, 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)
{
"featureSubscriptionType": "ENTERPRISE_YEAR",
"hourlyRate": {
"amount": 15
},
"id": "5g3g57bt0cb2548e22e6l9cd",
"imageUrl": "string",
"memberships": [
{
"hourlyRate": {
"amount": 15
},
"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)
{
"featureSubscriptionType": "ENTERPRISE_YEAR",
"hourlyRate": {
"amount": 15
},
"id": "5g3g57bt0cb2548e22e6l9cd",
"imageUrl": "string",
"memberships": [
{
"hourlyRate": {
"amount": 15
},
"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
page-size
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: 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"
},
"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: 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: 200
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"
"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"
},
"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,
"timeInterval": {
"start": "2020-05-15T08:00:00",
"end": "2020-05-15T09:00: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: 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,
"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