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

May 10, 2021
  • Added missing costRate in user object
  • 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)
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/v1
API Base Endpoint for Reports
https://reports.api.clockify.me/v1
Example request
curl -H "content-type: application/json" -H "X-Api-Key: yourAPIkey" -X GET https://api.clockify.me/api/v1/user
Terms 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 "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 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

Client

Find clients on workspace

GET /workspaces/{workspaceId}/clients
archived: boolean
in query

If true, you'll get only archived clients. If false, you'll get only active clients.

name: string
in query

If provided, clients will be filtered by name

page: integer 1
in query

page

page-size: integer 50
in query

page-size

sort-column: string
in query

NAME

sort-order: string
in query

ASCENDING, DESCENDING

200 OK

OK

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Content-Types: */*
Response Example (200 OK) 
[
  {
    "id": "5b1e52ff0cb8792ed75992c1",
    "name": "Client X",
    "workspaceId": "5c0fe3290cl84304845dbf1f",
    "archived": "false"
  }
]
Client

Add a new client to workspace

POST /workspaces/{workspaceId}/clients
Request Content-Types: application/json
Request Example
{
  "name": "Client"
}
201 Created

Created

400 Bad Request

Client with that name already exists on workspace

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Content-Types: */*
Response Example (201 Created) 
{
  "id": "5b1e52ff0cb8792ed75992c1",
  "name": "Client",
  "workspaceId": "5c0fe3290cl84304845dbf1f"
}
Client

Update client

PUT /workspaces/{workspaceId}/clients/{clientId}
archive-projects: boolean
in query

Controls whether archiving client will result in archiving all projects of given client

Request Content-Types: application/json
Request Example
{
  "archived": false,
  "name": "Client"
}
200 OK

OK

201 Created

Created

400 Bad Request

Bad Request

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not found

Response Content-Types: */*
Response Example (200 OK) 
{
  "archived": true,
  "id": "5bf6d2b9b079876a34621638",
  "name": "Client",
  "workspaceId": "5bfd36c4b0798777049512e3"
}
Client

Delete client

DELETE /workspaces/{workspaceId}/clients/{clientId}
200 OK

OK

204 No Content

No Content

400 Bad Request

Bad Request

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not found

Response Content-Types: */*
Response Example (200 OK) 
{
  "archived": true,
  "id": "5bf6d2b9b079876a34621638",
  "name": "Client",
  "workspaceId": "5bfd36c4b0798777049512e3"
}

Project

Endpoints for manipulating PROJECT resource

Project

Get all projects on workspace

GET /workspaces/{workspaceId}/projects
archived: boolean
in query

If true, you'll get only archived projects. If false, you'll get only active projects.

name: string
in query

If provided, projects will be filtered by name.

page: integer 1
in query

page

page-size: integer 50
in query

page-size

billable: boolean
in query

If provided, projects will be filtered by billable status.

clients: Array < String >
in query

If provided, projects will be filtered by client ID(s).

contains-client: boolean
in query

If provided, projects will be filtered by whether they have a client.

client-status: string
in query

Possible values: ACTIVE, ARCHIVED

users: Array < String >
in query

If provided, projects will be filtered by user ID(s) who have access.

contains-users: boolean
in query

If provided, projects will be filtered by whether they have users.

user-status: string
in query

Possible values: ACTIVE, INACTIVE

is-template: boolean
in query

If provided, projects will be filtered by whether they are used as a template.

sort-column: string
in query

Possible values: NAME, CLIENT_NAME, DURATION.

sort-order: string
in query

Possible values: ASCENDING, DESCENDING.

200 OK

OK

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

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
    }
  }
]
Project

Find project by ID

GET /workspaces/{workspaceId}/projects/{projectId}
200 OK

OK

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

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
  }
}
Project

Add a new project to workspace

POST /workspaces/{workspaceId}/projects
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
}
201 Created

Created

400 Bad Request

Project with that name already exists on workspace.

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

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",
}
Project

Update project on workspace

PUT /workspaces/{workspaceId}/projects/{projectId}
estimate type

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"
}
201 Created

Created

400 Bad Request

Project with that name already exists on workspace.

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

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"
}
Project

Update project estimate

PATCH /workspaces/{workspaceId}/projects/{projectId}/estimate
active

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.

reset

Choose if estimate resets each month. Possible values: null and MONTHLY

type

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
  }
}
200 OK

OK

400 Bad Request

Only one type of estimate can be active at a time.

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

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"
}
Project

Update project memberships

PATCH /workspaces/{workspaceId}/projects/{projectId}/memberships
Request Content-Types: application/json
Request Example

{
  "memberships": [
    {
      "userId": "5ef31421f9ef6228d72d8833", (can be group ID or user ID)
      "hourlyRate": {
        "amount": 2000
      } (optional)
    }
  ]
}
200 OK

OK

400 Bad Request

User or group is not a member of this workspace.

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

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"
}
Project

Update project template

PATCH /workspaces/{workspaceId}/projects/{projectId}/template
Request Content-Types: application/json
Request Example

{
  "isTemplate": "true"
}
201 Created

Created

400 Bad Request

Project with that name already exists on workspace.

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

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"
}
Project

Delete project from workspace

DELETE /workspaces/{workspaceId}/projects/{id}
200 OK

OK

204 No Content

No Content

400 Bad Request

Project with specified id not found

401 Unauthorized

Unauthorized

403 Forbidden

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

Tag

Find tags on workspace

GET /workspaces/{workspaceId}/tags
name: string
in query

If provided, tags will be filtered by name.

archived: boolean
in query

If true, you'll get only archived tags. If false, you'll get only active tags.

page: integer 1
in query

page

page-size: integer 50
in query

page-size

200 OK

OK

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Content-Types: */*
Response Example (200 OK) 
[
  {
    "id": "5a7c5d2db079870147fra234",
    "name": "Tag 1",
    "workspaceId": "5g3g57bt0cb2548e22e6l9cd",
    "archived": "false"
  }
]
Tag

Add a new tag to workspace

POST /workspaces/{workspaceId}/tags
Request Content-Types: application/json
Request Example
{
  "name": "Tag 1"
}
201 Created

Created

400 Bad Request

Tag with that name already exists on workspace

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Content-Types: */*
Response Example (201 Created) 
{
  "id": "5a7c5d2db079870147fra234",
  "name": "Tag 1",
  "workspaceId": "5g3g57bt0cb2548e22e6l9cd"
}
Tag

Update tag

PUT /workspaces/{workspaceId}/tags/{tagId}
Request Content-Types: application/json
Request Example
{
  "archived": false,
  "name": "Tag"
}
200 OK

OK

201 Created

Created

400 Bad Request

Bad Request

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not found

Response Content-Types: */*
Response Example (200 OK) 
{
  "archived": true,
  "id": "5bf6d2b9b079876a34621638",
  "name": "Tag",
  "workspaceId": "5bfd36c4b0798777049512e3"
}
Tag

Delete tag

DELETE /workspaces/{workspaceId}/tags/{tagId}
200 OK

OK

204 No Content

No Content

400 Bad Request

Bad Request

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not found

Response Content-Types: */*
Response Example (200 OK) 
{
  "archived": true,
  "id": "5bf6d2b9b079876a34621638",
  "name": "Tag",
  "workspaceId": "5bfd36c4b0798777049512e3"
}

Task

Endpoints for manipulating TASK resource

Task

Find tasks on project

GET /workspaces/{workspaceId}/projects/{projectId}/tasks
is-active: boolean
in query

If provided and true, only active tasks will be returned. Otherwise only finished tasks will be returned.

name: string
in query

If provided, tasks will be filtered by name.

page: integer 1
in query

page

page-size: integer 50
in query

page-size

200 OK

OK

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Content-Types: */*
Response Example (200 OK) 
[
  {
    "assigneeIds": ["593e40aab0798735d0392a2d"],
    "estimate": "PT0S",
    "id": "5b1e6b160cb8793dd93ec120",
    "name": "Task 1",
    "projectId": "5b1667790cb8797321f3d664",
    "billable": "true",
    "status": "ACTIVE" (Status: ACTIVE, DONE)
  }
]
Task

Find task on project by ID

GET /workspaces/{workspaceId}/projects/{projectId}/tasks/{taskId}
200 OK

OK

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Content-Types: */*
Response Example (200 OK) 
{
  "assigneeIds": ["593e40aab0798735d0392a2d"],
  "estimate": "PT0S",
  "id": "5b1e6b160cb8793dd93ec120",
  "name": "Task 1",
  "projectId": "5b1667790cb8797321f3d664",
  "billable": "true",
  "status": "ACTIVE" (Status: ACTIVE, DONE)
}
Task

Add a new task on project

POST /workspaces/{workspaceId}/projects/{projectId}/tasks
Request Content-Types: application/json
Request Example
{
  "name": "Task 1",

  // OPTIONAL
  "assigneeIds": ["593e40aab0798735d0392a2d"],
  "estimate": "PT2H",
  "status": "ACTIVE" (ACTIVE, DONE)
}
201 Created

Created

400 Bad Request

Task with that name already exists on project, or specified project doesn't exist

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Content-Types: */*
Response Example (201 Created) 
{
  "assigneeIds": ["593e40aab0798735d0392a2d"],
  "estimate": "PT2H",
  "id": "5b1e6b160cb8793dd93ec120",
  "name": "Task 1",
  "projectId": "5b1667790cb8797321f3d664",
  "billable": "true",
  "status": "ACTIVE"
}
Task

Update task on project

PUT /workspaces/{workspaceId}/projects/{projectId}/tasks/{taskId}
Request Content-Types: application/json
Request Example
{
  "name": "Task 1",
  "assigneeIds": ["593e40aab0798735d0392a2d"],
  "estimate": "PT2H",
  "billable": "true",
  "status": "ACTIVE" (ACTIVE, DONE)
}
201 Created

Created

400 Bad Request

Task with that name already exists on project, or specified project doesn't exist

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Content-Types: */*
Response Example (201 Created) 
{
  "assigneeIds": ["593e40aab0798735d0392a2d"],
  "estimate": "PT2H",
  "id": "5b1e6b160cb8793dd93ec120",
  "name": "Task 1",
  "projectId": "5b1667790cb8797321f3d664",
  "billable": "true",
  "status": "ACTIVE"
}
Task

Delete task from project

DELETE /workspaces/{workspaceId}/projects/{projectId}/tasks/{taskId}
200 OK

OK

204 No Content

No Content

400 Bad Request

Project with specified id not found

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

Response Content-Types: */*
Response Example (200 OK) 
{
  "assigneeIds": ["593e40aab0798735d0392a2d"],
  "estimate": "PT2H",
  "id": "5b1e6b160cb8793dd93ec120",
  "name": "Task 1",
  "projectId": "5b1667790cb8797321f3d664",
  "billable": "true",
  "status": "DONE"
}

Time entry

Endpoints for manipulating TIMEENTRY resource

Time entry

Get your time entries on workspace

Gets a time entry for specified user on workspace. Filters can be applied as query parameters listed below

GET /workspaces/{workspaceId}/user/{userId}/time-entries

Requires WORKSPACE_OWN or WORKSPACE_ADMIN permissions to see other user's time entries.

description: string
in query

If provided, time entries will be filtered by description.

start: string
in query

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.

end: string
in query

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.

project: string
in query

If provided, time entries will be filtered by project.

task: string
in query

If provided, time entries will be filtered by task.

tags: string[]
in query

If provided, time entries will be filtered by tags. This parameter is an array of tag ids.

Array values passed as multiple parameters: ?tags=tagId_1&tags=tagId_2
project-required: boolean 1
in query

If provided, only time entries with project will be returned.

task-required: boolean 1
in query

If provided, only time entries with task will be returned.

consider-duration-format: boolean
in query

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.

hydrated: boolean
in query

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.

in-progress: boolean
in query

If provided, all other filters will be ignored and, if present, currently running time entry will be returned.

page: integer 1
in query

page

page-size: integer 50
in query

page-size

200 OK

OK

400 Bad Request

User with given ID doesn't exist

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

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"
    }
  ]
]
Time entry

Get a specific time entry on workspace

GET /workspaces/{workspaceId}/time-entries/{id}
consider-duration-format: boolean
in query

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.

hydrated: boolean
in query

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.

200 OK

OK

400 Bad Request

Time entry with given ID doesn't exist

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

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"
    }
  ]
}
Time entry

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.

POST /workspaces/{workspaceId}/time-entries
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"
    }
  ]
}
201 Created

Created

400 Bad Request

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);

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

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"
    }
  ]
}
Time entry

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"}

POST /workspaces/{workspaceId}/user/{userId}/time-entries
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"
    }
  ]
}
201 Created

Created

400 Bad Request

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)

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

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"
    }
  ]
}
Time entry

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.

PATCH /workspaces/{workspaceId}/user/{userId}/time-entries
Request Content-Types: application/json
Request Example
{
  "end": "2018-06-12T14:01:41Z"
}
200 OK

OK

204 No Content

No Content

400 Bad Request

Required information is not present on currently running time entry. Check your workspace settings.

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

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"
    }
  ]
}
Time entry

Update time entry on workspace

PUT /workspaces/{workspaceId}/time-entries/{id}
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"
    }
  ]
}
200 OK

OK

201 Created

Created

400 Bad Request

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

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

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"
    }
  ]
}
Time entry

Mark time entries as invoiced

PATCH /workspaces/{workspaceId}/time-entries/invoiced
Request Content-Types: application/json
Request Example
{
  "timeEntryIds": ["5a7c5d2db079870147fra134"],
  "invoiced" : true
}
200 OK

OK

400 Bad Request

Bad Request

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Time entry

Delete time entry from workspace

DELETE /workspaces/{workspaceId}/time-entries/{id}
204 No Content

No Content

400 Bad Request

Time entry with given ID doesn't exist or doesn't belong to workspace

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

Response Content-Types: */*

User

Endpoints for manipulating USER resource

User

Get currently logged in user's info

GET /user
200 OK

OK

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

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"
}
User

Find all users on workspace

GET /workspaces/{workspaceId}/users
page: integer 1
in query

page

page-size: integer 50
in query

page-size

memberships: string
in query

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).

email: string
in query

If provided, you'll get a filtered list of users that contain the provided string in their email address.

projectId: string
in query

If provided, you'll get a list of users that have access to the project.

name: string
in query

If provided, you'll get a filtered list of users that contain the provided string in their name.

status: string
in query

If provided, you'll get a filtered list of users with the corresponding status. Possible values: PENDING, ACTIVE, DECLINED, INACTIVE

sort-column: string
in query

Possible values: EMAIL, NAME, HOURLYRATE

sort-order: string
in query

Possible values: ASCENDING, DESCENDING

includeRoles: boolean
in query

If you pass along includeRoles=true, you'll get each user's detailed manager role (including projects and members for whome they're managers)

Array values passed as multiple parameters: ?email=@gmail&memberships=NONE&page-size=100&status=ACTIVE
200 OK

OK

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

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"
          }
        ]
      }
    ]
  }
]
User

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.

POST /workspaces/{workspaceId}/users
Request Content-Types: application/json
Request Example
{
  "email": "example@email.com"
}
200 OK

OK

201 Created

Created

400 Bad Request

Bad Request

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

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
  }
}
User

Update user's workspace status

PUT /workspaces/{workspaceId}/users/{userId}
Request Content-Types: application/json
Request Example
{
  "membershipStatus": "INACTIVE" (ACTIVE, INACTIVE)
}
200 OK

OK

201 Created

Created

400 Bad Request

Bad Request

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

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
  }
}
User

Remove user from workspace

DELETE /workspaces/{workspaceId}/users/{userId}
200 OK

OK

204 No Content

No Content

400 Bad Request

Bad Request

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not found

Response Content-Types: */*

Group

Endpoints for manipulating group resource

Group

Find all groups on workspace

GET /workspaces/{workspaceId}/user-groups
page: integer 1
in query

page

page-size: integer 50
in query

page-size

projectId: string
in query

projectId

name: string
in query

name

sort-order: string
in query

ASCENDING, DESCENDING

sort-column: string
in query

NAME

200 OK

OK

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Content-Types: */*
Response Example (200 OK) 
[
  {
    "id": "5a0b0c2c307987125438b903",
    "name": "Admins",
    "workspaceId": "5a0b01dcb07987125438b902",
    "userIds": [
        "5a0ab5acb07987125438b60f", 
        "599b90jnb0798723decee4f0", 
        "5a1d311db079872b2a7b5a2f"
    ]
  }
]
Group

Add a new group to workspace

POST /workspaces/{workspaceId}/user-groups
Request Content-Types: application/json
Request Example
{
  "name": "My group"
}
201 Created

Created

400 Bad Request

Tag with that name already exists on workspace

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Content-Types: */*
Response Example (201 Created) 
{
  "id": "5a7c5d2d2079870147fra234",
  "name": "My group",
  "workspaceId": "5g3g57bt0cb2548e22e6l9cd"
}
Group

Update group name

PUT /workspaces/{workspaceId}/user-groups/{userGroupId}
Request Content-Types: application/json
Request Example
{
  "name": "Group"
}
200 OK

OK

201 Created

Created

400 Bad Request

Bad Request

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not found

Response Content-Types: */*
Response Example (200 OK) 
{
  "id": "5bf6d2b9b079876a34621638",
  "name": "Group",
  "userIds": [
    "string"
  ],
  "workspaceId": "5bfd36c4b0798777049512e3"
}
Group

Delete group

DELETE /workspaces/{workspaceId}/user-groups/{userGroupId}
200 OK

OK

204 No Content

No Content

400 Bad Request

Bad Request

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not found

Response Content-Types: */*
Response Example (200 OK) 
{
  "id": "5bf6d2b9b079876a34621638",
  "name": "Group",
  "userIds": [
    "5b23d2b9b079876a34621638"
  ],
  "workspaceId": "5bfd36c4b0798777049512e3"
}
Group

Add users to group

POST /workspaces/{workspaceId}/user-groups/{userGroupId}/users
Request Content-Types: application/json
Request Example
{
  "userId": "5bf6d2b9b079876a34621635"
}
200 OK

OK

201 Created

Created

400 Bad Request

Bad Request

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not found

Response Content-Types: */*
Response Example (200 OK) 
{
  "id": "5bf6d2b9b079876a34621638",
  "name": "Group",
  "userIds": [
    "5b23d2b9b079876a34621638"
  ],
  "workspaceId": "5bfd36c4b0798777049512e3"
}
Group

Remove user from group

DELETE /workspaces/{workspaceId}/user-groups/{userGroupId}/users/{userId}
200 OK

OK

204 No Content

No Content

400 Bad Request

Bad Request

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not found

Response Content-Types: */*
Response Example (200 OK) 
{
  "id": "5bf6d2b9b079876a34621638",
  "name": "Group",
  "userIds": [
    "5b23d2b9b079876a34621638"
  ],
  "workspaceId": "5bfd36c4b0798777049512e3"
}

Workspace

Endpoints for manipulating WORKSPACE resource

Workspace

Get all my workspaces

GET /workspaces
200 OK

OK

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

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.

Custom fields

Get custom fields on workspace

GET /workspaces/{workspaceId}/custom-fields
name: string
in query
status: string
in query

INACTIVE, VISIBLE, INVISIBLE

200 OK

OK

400 Bad Request

Doesn't exist

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

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)
      }
    ]
  }
]
Custom fields

Get custom fields on project

GET /workspaces/{workspaceId}/projects/{projectid}/custom-fields
name: string
in query

status: string
in query

INACTIVE, VISIBLE, INVISIBLE

200 OK

OK

400 Bad Request

Doesn't exist

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

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)
      }
    ]
  }
]
Custom fields

Update custom field on project

PATCH /workspaces/{workspaceId}/projects/{projectid}/custom-fields/{customFieldId}
Request Content-Types: application/json
Request Example
{
  "defaultValue" : "San Francisco",
  "status" : "INVISIBLE" (INACTIVE, VISIBLE, INVISIBLE)
}
201 Success

Success

400 Bad Request

Task with that name already exists on project, or specified project doesn't exist

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

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)
    }
  ]
}
Custom fields

Remove custom field from project

DELETE /workspaces/{workspaceId}/projects/{projectid}/custom-fields/{customFieldId}
200 OK

OK

400 Bad Request

Doesn't exist

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

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/v1
Reports

Summary report

POST /workspaces/{workspaceId}/reports/summary
"groups" in "summaryFilter"

Possible values: PROJECT, CLIENT, TASK, TAG, DATE, USER, USER_GROUP, TIMEENTRY

"sortColumn" in "summaryFilter"

Possible values: GROUP, DURATION, AMOUNT

"amountShown"

Possible values: HIDE_AMOUNT, EARNED, COST, PROFIT

"exportType"

Possible values: JSON, CSV, XLSX, PDF

"sortOrder"

Possible values: ASCENDING, DESCENDING

"contains" in any filter (except tags)

CONTAINS, DOES_NOT_CONTAIN

"containedInTimeentry" in tag filter

CONTAINS, CONTAINS_ONLY, DOES_NOT_CONTAIN

"status" in any filter

Projects, clients, tags: ALL, ACTIVE, ARCHIVED
Users: ALL, ACTIVE, INACTIVE
Tasks: ALL, ACTIVE, DONE

"timeZone"

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"
    }
  ]
}
400 Bad Request

Bad Request

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

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",
        ]
      ]
    }
  ]
}
Reports

Detailed report

POST /workspaces/{workspaceId}/reports/detailed
"sortColumn" in "detailedFilter"

Possible values: ID, DESCRIPTION, USER, DURATION, DATE

"amountShown"

Possible values: HIDE_AMOUNT, EARNED, COST, PROFIT

"exportType"

Possible values: JSON, CSV, XLSX, PDF

"sortColumn"

Possible values: GROUP, DURATION, AMOUNT

"sortOrder"

Possible values: ASCENDING, DESCENDING

"contains" in any filter (except tags)

CONTAINS, DOES_NOT_CONTAIN

"containedInTimeentry" in tag filter

CONTAINS, CONTAINS_ONLY, DOES_NOT_CONTAIN

"status" in any filter

Projects, clients, tags: ALL, ACTIVE, ARCHIVED
Users: ALL, ACTIVE, INACTIVE
Tasks: ALL, ACTIVE, DONE

"pageSize" in "detailedFilter"

Max value: 200

"timeZone"

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"
    }
  ]
}
400 Bad Request

Bad Request

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

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",
        "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"
    }
  ]
}
Reports

Weekly report

POST /workspaces/{workspaceId}/reports/weekly
"group" in "weeklyFilter"

Possible values: PROJECT, USER

"subgroup" in "weeklyFilter"

Possible values: TIME, EARNED

"amountShown"

Possible values: HIDE_AMOUNT, EARNED, COST, PROFIT

"exportType"

Possible values: JSON, CSV, XLSX, PDF

"sortColumn"

Possible values: GROUP, DURATION, AMOUNT

"sortOrder"

Possible values: ASCENDING, DESCENDING

"contains" in any filter (except tags)

CONTAINS, DOES_NOT_CONTAIN

"containedInTimeentry" in tag filter

CONTAINS, CONTAINS_ONLY, DOES_NOT_CONTAIN

"status" in any filter

Projects, clients, tags: ALL, ACTIVE, ARCHIVED
Users: ALL, ACTIVE, INACTIVE
Tasks: ALL, ACTIVE, DONE

"timeZone"

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"
    }
  ]
}
400 Bad Request

Bad Request

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

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
Shared reports

Get all my shared reports

GET /workspaces/{workspaceId}/shared-reports

Gets all shared reports for current user on given workspace

page: integer 1
in query

Current page number

pageSize: integer 50
in query

Number of reports shown by page. Max size is 200.

200 OK

OK

400 Bad Request

Bad Request

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not found

Response Content-Types: application/json
Response Example (200 OK) 
{
  "reports": [
    {
      "name": "Shared report",
      "link": "string (http://example.url/5efc69f3784d5a36bb239e27)",
      "id": "5efc69f3784d5a36bb239e27",
      "visibleToUsers": [
        {
          "id": "5bf6d2b9b079876a34621635",
          "name": "Entity name"
        }
      ],
      "fixedDate": true,
      "type": "SUMMARY",
      "isPublic": true,
      "visibleToUserGroups": [
        {
          "id": "5bf6d2b9b079876a34621635",
          "name": "Entity name"
        }
      ]
    }
  ],
  "count": 1
}
Shared reports

Generate shared report by ID

GET /shared-reports/{sharedReportId}

Response depends on report type and export type. Given example is for SUMMARY report and JSON exportType.

dateRangeStart: string
in query

Start of selected date range.

dateRangeEnd: string
in query

End of selected date range.

sortOrder: string
in query

Sets sort order for report data

sortColumn: string
in query

Controls timeentry/group sorting criteria.

exportType: string JSON, CSV, XLSX, PDF
in query

This parameter decides data format of generated report

page: integer
in query

Page number

pageSize: integer
in query

Number of entites shown by page

200 OK

OK

400 Bad Request

Bad Request

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not found

Response Content-Types: application/json
Response Example (200 OK) 
{
  "totals": [
    {
      "_id": ",
      "totalTime": 2760,
      "totalBillableTime": 0,
      "totalAmount": 0.0,
      "entriesCount":1
    }
  ],
  "groupOne": [
    "_id": "5ef1cf219f130f232cc34dd5",
    "duration": 2760,
    "amount": 0.0,
    "children": [
      {
        "_id": "5ef1cf219f130f232cc3xge8",
        "duration": 2760,
        "amount": 0.0,
        "name": "Timeentry description",
        "name": null
      }
    ]
  ],
  "filters": {
    "id": "5efdd01407aeb34a9f1161a1",
    "workspaceId": "5ef1cf229f130f232cc34ddf",
    "userId": "5ef1cf219f130f232cc34ddc",
    "name": "Saved report v1",
    "visibleToUserGroups": null,
    "visibleToUsers": null,
    "fixedDate": false,
    "type": "SUMMARY",
    "filter": {
      "dateRangeStart": "2020-05-10T00:00:00.000Z",
      "dateRangeEnd": "2020-05-16T23:59:59.000Z",
      "dateRangeType": "THIS_WEEK",
      "dateFormat": "MM/DD/YYYY",
      "timeFormat": HOUR12,
      "weekStart": "MONDAY",
      "users": {
        "contains": "CONTAINS",
        "ids": [
          "string"
        ],
        "status": "ACTIVE"
      },
      "userGroups": {
        "contains": "CONTAINS",
        "ids": [
          "string"
        ],
        "status": "ACTIVE"
      },
      "clients": {
        "contains": "CONTAINS",
        "ids": [
          "string"
        ],
        "status": "ACTIVE"
      },
      "projects": {
        "contains": "CONTAINS",
        "ids": [
          "string"
        ],
        "status": "ACTIVE"
      },
      "tasks": {
        "contains": "CONTAINS",
        "ids": [
          "string"
        ],
        "status": "ACTIVE"
      },
      "tags": {
        "containedInTimeentry": "CONTAINS_ONLY",
        "contains": "CONTAINS",
        "ids": [
          "string"
        ],
        "status": "ACTIVE"
      },
      "billable": true,
      "description": "Filter description",
      "withoutDescription": true,
      "detailedFilter": {
        "sortColumn": "DATE",
        "page": 1,
        "pageSize": 50,
        "auditFilter": {
          "withoutProject": true,
          "withoutTask": true,
          "duration": 3600,
          "durationShorter": true
        }
      },
      "summaryFilter": {
        "groups": [
          "string"
        ],
        "sortColumn": "GROUP"
      },
      "weeklyFilter": {
        "group": "USER",
        "subgroup": "TIME"
      },
      "sortOrder": "DESCENDING",
      "exportType": "JSON",
      "rounding": false,
      "amountShown": "HIDE_AMOUNT",
      "customFields": [
        {
          "id": "5bfd36c4b0798777049512e2",
          "value": "30",
          "type": "NUMBER",
          "numberCondition": "EQUAL",
          "empty": "boolean"
        }
      ],
      "user": {
        "id": "5ef1cf219f130f232cc34ddc",
        "name": "User Name",
        "email": "user.name@example.com",
        "dateFormat": "MM/DD/YYYY",
        "timeFormat": "HOUR12",
        "timeZone": "Europe/Frankfurt",
        "weekStart": "MONDAY",
      },
      "workspace": {
        "id": "5ef1cf229f130f232cc34ddf",
        "name": "User's workspace'",
        "workspaceSettings": {
          "onlyAdminsSeeAllTimeEntries": false,
          "onlyAdminsSeePublicProjectEntries": true,
          "onlyAdminsSeeBillableRates": false,
          "projectGroupingLabel": "client",
          "lockDate": null,
          "costRateActive": true,
        },
        "currency": "USD",
        "imageUrl": ",
        "onlyAdminsSeeBillableRates": true,
        "trackTimeDownToSeconds": true,,
      },
      "subscriptionPlan": "SPECIAL",
      "isAdminOrOwner": true
    }
  },

}
Shared reports

Create shared report

POST /workspaces/{workspaceId}/shared-reports

Saves shared report with name, options and report filter

Request Content-Types: application/json
Request Example
{
  "name": "Saved report v1",
  "isPublic": true,
  "fixedDate": false,
  "type": "SUMMARY",
  "filter": {
    "dateRangeStart": "2020-05-10T00:00:00.000Z",
    "dateRangeEnd": "2020-05-16T23:59:59.000Z",
    "dateRangeType": "THIS_WEEK",
    "dateFormat": "MM/DD/YYYY",
    "timeFormat": HOUR12,
    "weekStart": "MONDAY",
    "users": {
      "contains": "CONTAINS",
      "ids": [
        "string"
      ],
      "status": "ACTIVE"
    },
    "userGroups": {
      "contains": "CONTAINS",
      "ids": [
        "string"
      ],
      "status": "ACTIVE"
    },
    "clients": {
      "contains": "CONTAINS",
      "ids": [
        "string"
      ],
      "status": "ACTIVE"
    },
    "projects": {
      "contains": "CONTAINS",
      "ids": [
        "string"
      ],
      "status": "ACTIVE"
    },
    "tasks": {
      "contains": "CONTAINS",
      "ids": [
        "string"
      ],
      "status": "ACTIVE"
    },
    "tags": {
      "containedInTimeentry": "CONTAINS_ONLY",
      "contains": "CONTAINS",
      "ids": [
        "string"
      ],
      "status": "ACTIVE"
    },
    "billable": true,
    "description": "Filter description",
    "withoutDescription": true,
    "detailedFilter": {
      "sortColumn": "DATE",
      "page": 1,
      "pageSize": 50,
      "auditFilter": {
        "withoutProject": true,
        "withoutTask": true,
        "duration": 3600,
        "durationShorter": true
      }
    },
    "summaryFilter": {
      "groups": [
        "string"
      ],
      "sortColumn": "GROUP"
    },
    "weeklyFilter": {
      "group": "USER",
      "subgroup": "TIME"
    },
    "sortOrder": "DESCENDING",
    "exportType": "JSON",
    "rounding": false,
    "amountShown": "HIDE_AMOUNT",
    "customFields": [
      {
        "id": "5bfd36c4b0798777049512e2",
        "value": "30",
        "type": "NUMBER",
        "numberCondition": "EQUAL",
        "empty": "boolean"
      }
    ]
  }
}
200 OK

OK

400 Bad Request

Bad Request

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not found

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "5efdd01407aeb34a9f1161a1",
  "workspaceId": "5ef1cf229f130f232cc34ddf",
  "userId": "5ef1cf219f130f232cc34ddc",
  "name": "Saved report v1",
  "visibleToUserGroups": null,
  "visibleToUsers": null,
  "fixedDate": false,
  "type": "SUMMARY",
  "filter": {
    "dateRangeStart": "2020-05-10T00:00:00.000Z",
    "dateRangeEnd": "2020-05-16T23:59:59.000Z",
    "dateRangeType": "THIS_WEEK",
    "dateFormat": "MM/DD/YYYY",
    "timeFormat": HOUR12,
    "weekStart": "MONDAY",
    "users": {
      "contains": "CONTAINS",
      "ids": [
        "string"
      ],
      "status": "ACTIVE"
    },
    "userGroups": {
      "contains": "CONTAINS",
      "ids": [
        "string"
      ],
      "status": "ACTIVE"
    },
    "clients": {
      "contains": "CONTAINS",
      "ids": [
        "string"
      ],
      "status": "ACTIVE"
    },
    "projects": {
      "contains": "CONTAINS",
      "ids": [
        "string"
      ],
      "status": "ACTIVE"
    },
    "tasks": {
      "contains": "CONTAINS",
      "ids": [
        "string"
      ],
      "status": "ACTIVE"
    },
    "tags": {
      "containedInTimeentry": "CONTAINS_ONLY",
      "contains": "CONTAINS",
      "ids": [
        "string"
      ],
      "status": "ACTIVE"
    },
    "billable": true,
    "description": "Filter description",
    "withoutDescription": true,
    "detailedFilter": {
      "sortColumn": "DATE",
      "page": 1,
      "pageSize": 50,
      "auditFilter": {
        "withoutProject": true,
        "withoutTask": true,
        "duration": 3600,
        "durationShorter": true
      }
    },
    "summaryFilter": {
      "groups": [
        "string"
      ],
      "sortColumn": "GROUP"
    },
    "weeklyFilter": {
      "group": "USER",
      "subgroup": "TIME"
    },
    "sortOrder": "DESCENDING",
    "exportType": "JSON",
    "rounding": false,
    "amountShown": "HIDE_AMOUNT",
    "customFields": [
      {
        "id": "5bfd36c4b0798777049512e2",
        "value": "30",
        "type": "NUMBER",
        "numberCondition": "EQUAL",
        "empty": "boolean"
      }
    ]
  }
}
Shared reports

Update shared report

PUT /workspaces/{workspaceId}/shared-reports/{sharedReportId}

Updates shared report name and/or options

Request Content-Types: application/json
Request Example
{
  "name": "Saved report v1",
  "isPublic": true,
  "fixedDate": false,
  "visibleToUsers": [],
  "visibleToUserGroups": []
}
200 OK

OK

400 Bad Request

Bad Request

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not found

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "5efdd01407aeb34a9f1161a1",
  "workspaceId": "5ef1cf229f130f232cc34ddf",
  "userId": "5ef1cf219f130f232cc34ddc",
  "name": "Saved report v1",
  "visibleToUserGroups": null,
  "visibleToUsers": null,
  "fixedDate": false,
  "type": "SUMMARY",
  "filter": {
    "dateRangeStart": "2020-05-10T00:00:00.000Z",
    "dateRangeEnd": "2020-05-16T23:59:59.000Z",
    "dateRangeType": "THIS_WEEK",
    "dateFormat": "MM/DD/YYYY",
    "timeFORMAT": HOUR12,
    "weekStart": "MONDAY",
    "users": {
      "contains": "CONTAINS",
      "ids": [
        "string"
      ],
      "status": "ACTIVE"
    },
    "userGroups": {
      "contains": "CONTAINS",
      "ids": [
        "string"
      ],
      "status": "ACTIVE"
    },
    "clients": {
      "contains": "CONTAINS",
      "ids": [
        "string"
      ],
      "status": "ACTIVE"
    },
    "projects": {
      "contains": "CONTAINS",
      "ids": [
        "string"
      ],
      "status": "ACTIVE"
    },
    "tasks": {
      "contains": "CONTAINS",
      "ids": [
        "string"
      ],
      "status": "ACTIVE"
    },
    "tags": {
      "containedInTimeentry": "CONTAINS_ONLY",
      "contains": "CONTAINS",
      "ids": [
        "string"
      ],
      "status": "ACTIVE"
    },
    "billable": true,
    "description": "Filter description",
    "withoutDescription": true,
    "detailedFilter": {
      "sortColumn": "DATE",
      "page": 1,
      "pageSize": 50,
      "auditFilter": {
        "withoutProject": true,
        "withoutTask": true,
        "duration": 3600,
        "durationShorter": true
      }
    },
    "summaryFilter": {
      "groups": [
        "string"
      ],
      "sortColumn": "GROUP"
    },
    "weeklyFilter": {
      "group": "USER",
      "subgroup": "TIME"
    },
    "sortOrder": "DESCENDING",
    "exportType": "JSON",
    "rounding": false,
    "amountShown": "HIDE_AMOUNT",
    "customFields": [
      {
        "id": "5bfd36c4b0798777049512e2",
        "value": "30",
        "type": "NUMBER",
        "numberCondition": "EQUAL",
        "empty": "boolean"
      }
    ]
  }
}
Shared reports

Delete shared report

DELETE /workspaces/{workspaceId}/shared-reports/{sharedReportId}
204 No Content

No Content

400 Bad Request

Bad Request

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not found

Response Content-Types: application/json