Toggl API v3

• Changes in this version
• API response
• API token
• Authentication
• Tasks
• Workspaces
• Clients
• Projects
• Planned tasks
• Tags
• Users
• Code samples

Current API version is v3. Previous versions are still available but will be removed in the future: v1, v2.

Changes in this version

If user's task_retention_days (see "How long do tasks stay in the timer" in your Toggl settings) was set to 0, API didn't return today's tasks. This has been fixed.

When returning tasks, API incremented the user supplied end_date value by 24 hours. This has been fixed.

API returned 400 instead of 404 when the requested object was not found. This has been fixed.

with_related_data optional parameter has been added to the users API, allowing to get the user's tasks, projects, planned tasks, tags, workspaces and clients with a single HTTP request.

API response

The result of each action is communicated via standard HTTP response codes.

If a create or update action failed, HTTP status code 404 and an array of localized error messages will be returned (but there's an exception: if the requested object was not found, plaintext "Requested object not found" is returned instead of an array).

Example request

Example response

When request is successful (2xx), a nested response object is returned.

Example request

Example response

  {
      "data": {
          "description": "New task",
          "start": "2010-02-12T15:35:47+02:00",
          "billable": false,
          "workspace": {
              "name": "john.doe@gmail.com's workspace",
              "id": 31366
          },
          "duration": 0,
          "stop": null,
          "tag_names": [

          ],
          "id": 4269795
      },
      "related_data_updated_at": "2010-06-29T11:17:19+03:00"
  }

The response object consists of data and a timestamp. The related_data_updated_at timestamp tells you when the data related to the current user was modified. If you have previously remembered the value of related_data_updated_at, you could compare the values to see if new data is available for the user via API.

API token

Each user in Toggl.com has an API token. He or she can see this token when visiting "My settings".

If you're integrating a third party service with Toggl API, we suggest that instead of asking for Toggl users e-mail and password, you ask for the users Toggl API token. If e-mail and password get stolen, the attacker can use this data to attack the victims other accounts (for example, e-mail). This is not possible with the API token, as it is unique for the Toggl account.

If asking for the API token is too cumbersome - for example, in a mobile phone app or in other situations where copy-paste of API token is not possible - you could ask for Toggl users e-mail and password and use this information to create a Toggl session. Then you can retrieve the Toggl API token and use this for later authentication. Again, we suggest not to keep any e-mail and password information laying around - save the token instead, if you need to.

Authentication

To use the API, you need to authenticate yourself. This can be done via HTTP POST or HTTP Basic Auth. After successful authentication a session is created using a cookie.

If authentication fails, HTTP status code 403 is returned.

HTTP POST with e-mail and password

Example request

Example response

  {
      "data": {
          "email": "johndoe@gmail.com",
          "date_format": "%m/%d/%Y",
          "new_tasks_start_automatically": true,
          "language": "en_US",
          "api_token": "ffc3f3024ec5d40cee2e24d5ff023c12",
          "fullname": "John Doe",
          "task_retention_days": 9,
          "jquery_date_format": "m/d/Y",
          "default_workspace_id": 31366,
          "jquery_timeofday_format": "H:i",
          "beginning_of_week": 1,
          "id": 42182,
          "timeofday_format": "%H:%M"
      },
      "related_data_updated_at": "2010-06-29T11:17:19+03:00"
  }

HTTP POST with API token

Example request

Example response

  {
      "data": {
          "email": "johndoe@gmail.com",
          "date_format": "%m/%d/%Y",
          "new_tasks_start_automatically": true,
          "language": "en_US",
          "api_token": "ffc3f3024ec5d40cee2e24d5ff023c12",
          "fullname": "John Doe",
          "task_retention_days": 9,
          "jquery_date_format": "m/d/Y",
          "default_workspace_id": 31366,
          "jquery_timeofday_format": "H:i",
          "beginning_of_week": 1,
          "id": 42182,
          "timeofday_format": "%H:%M"
      },
      "related_data_updated_at": "2010-06-29T11:17:19+03:00"
  }  

HTTP Basic Auth with e-mail and password

Example request

Example response

  {
      "data": {
          "email": "johndoe@gmail.com",
          "date_format": "%m/%d/%Y",
          "new_tasks_start_automatically": true,
          "language": "en_US",
          "api_token": "ffc3f3024ec5d40cee2e24d5ff023c12",
          "fullname": "John Doe",
          "task_retention_days": 9,
          "jquery_date_format": "m/d/Y",
          "default_workspace_id": 31366,
          "jquery_timeofday_format": "H:i",
          "beginning_of_week": 1,
          "id": 42182,
          "timeofday_format": "%H:%M"
      },
      "related_data_updated_at": "2010-06-29T11:17:19+03:00"
  }

HTTP Basic Auth with API token

When using Basic Auth and API token, use the API token as username and string "api_token" as password.

Example request

Example response

  {
      "data": {
          "email": "johndoe@gmail.com",
          "date_format": "%m/%d/%Y",
          "new_tasks_start_automatically": true,
          "language": "en_US",
          "api_token": "ffc3f3024ec5d40cee2e24d5ff023c12",
          "fullname": "John Doe",
          "task_retention_days": 9,
          "jquery_date_format": "m/d/Y",
          "default_workspace_id": 31366,
          "jquery_timeofday_format": "H:i",
          "beginning_of_week": 1,
          "id": 42182,
          "timeofday_format": "%H:%M"
      },
      "related_data_updated_at": "2010-06-29T11:17:19+03:00"
  }

Tasks

Get tasks

Example request

Example response

  {
      "data": [
          {
              "duration": -1265981479,
              "billable": true,
              "workspace": {
                  "name": "john.doe@gmail.com's workspace",
                  "id": 31366
              },
              "stop": "2010-02-12T15:51:19+02:00",
              "id": 2913477,
              "project": {
                  "name": "Important project",
                  "id": 189657,
                  "client_project_name": "Important project"
              },
              "start": "2010-02-12T15:35:47+02:00",
              "tag_names": [
                  "API"
              ],
              "description": "Today's task"
          }
      ],
      "related_data_updated_at": "2010-06-29T11:17:19+03:00"
  }

By default, the number of days from the field "How long do tasks stay in the Timer" under "My settings" in Toggl is used to determine which tasks to return but you can specify another date range using start_date and end_date parameters.

Example request

Example response

  {
      "data": [
          {
              "duration": 900,
              "billable": true,
              "workspace": {
                  "name": "john.doe@gmail.com's workspace",
                  "id": 31366
              },
              "stop": "2010-02-12T15:51:19+02:00",
              "id": 2913477,
              "project": {
                  "name": "Important project",
                  "id": 189657,
                  "client_project_name": "Important project"
              },
              "start": "2010-02-12T15:35:47+02:00",
              "tag_names": [
                  "API"
              ],
              "description": "Todays task"
          }
      ],
      "related_data_updated_at": "2010-06-29T11:17:19+03:00"
  }

API accepts and returns date/time values in ISO 8601 format. Task durations are in seconds.

If the task is currently running, the duration attribute contains a negative value, denoting the start of the task in seconds since epoch (Jan 1 1970). You will be responsible for showing the correct duration to the end user. The correct duration can be calculated as current_time + duration, where current_time is the current time in seconds since epoch.

Create a new task

Example request

Example response

  {
      "data": {
          "duration": 900,
          "billable": true,
          "workspace": {
              "name": "john.doe@gmail.com's workspace",
              "id": 31366
          },
          "stop": null,
          "id": 2913477,
          "project": {
              "name": "Important project",
              "id": 189657,
              "client_project_name": "Important project"
          },
          "start": "2010-02-12T16:19:45+02:00",
          "tag_names": [
              "API"
          ],
          "description": "A new task"
      },
      "related_data_updated_at": "2010-06-29T11:17:19+03:00"
  }

The created_with text field is mandatory and will be used to track API usage. You should provide a meaningful value for this field to identify your third party service.

The project field is not mandatory - tasks can be created without a project.

There are two ways to set the project of the task being created: you can use the project field or leave it blank and use the client_project_name field instead. For example, when sending "Foobar Inc - Important project" as client_project_name, the client will be looked up by name ("Foobar Inc") and also the project will be looked up by name ("Important project"). If the client or the project with the supplied name is not found, it will be created on the fly.

Update a task

Example request

Example response

  {
      "data": {
          "duration": 1800,
          "billable": true,
          "workspace": {
              "name": "john.doe@gmail.com's workspace",
              "id": 31366
          },
          "stop": null,
          "id": 2913477,
          "project": {
              "name": "Important project",
              "id": 189657,
              "client_project_name": "Important project"
          },
          "start": "2010-02-12T16:19:45+02:00",
          "tag_names": [
              "API",
              "Example"
          ],
          "description": "Name changed"
      },
      "related_data_updated_at": "2010-06-29T11:17:19+03:00"
  }

Destroy a task

Example request

Example response

  {
      "data": null,
      "related_data_updated_at": "2010-06-29T13:06:08+03:00"
  }

Workspaces

Get workspaces

Example request

Example response

  {
      "data": [
          {
              "name": "john.doe@gmail.com's workspace",
              "id": 31366
          }
      ],
      "related_data_updated_at": "2010-06-29T11:17:19+03:00"
  }

Clients

Get clients

Example request

Example response

  {
      "data": [
          {
              "name": "Bart",
              "workspace": {
                  "name": "john.doe@gmail.com's workspace",
                  "id": 31366
              },
              "id": 105995,
              "hourly_rate": 45.0,
              "currency": "USD"
          }
      ],
      "related_data_updated_at": "2010-06-29T11:17:19+03:00"
  }

Projects

Get projects

Example request

Example response

  {
      "data": [
          {
              "name": "Important stuff",
              "billable": true,
              "workspace": {
                  "name": "john.doe@gmail.com's workspace",
                  "id": 31366 
              },
              "id": 188909,
              "fixed_fee": 0.0,
              "hourly_rate": 45.0,
              "is_fixed_fee": false,
              "client_project_name": "Important stuff",
              "estimated_workhours": 10,
              "automatically_calculate_estimated_workhours": false 
          } 
      ],
      "related_data_updated_at": "2010-06-29T11:17:19+03:00" 
  }

The "client_project_name" field is for convenience and renders both the client name and project name.

Create a new project

Example request

Example response

  {
      "data": {
          "name": "Another project",
          "billable": true,
          "workspace": {
              "name": "john.doe@gmail.com's workspace",
              "id": 31366 
          },
          "id": 279892,
          "fixed_fee": 0.0,
          "hourly_rate": 0.0,
          "is_fixed_fee": false,
          "client_project_name": "Another project",
          "estimated_workhours": 0,
          "automatically_calculate_estimated_workhours": false 
      },
      "related_data_updated_at": "2010-06-29T11:17:19+03:00" 
  }

Update a project

Example request

Example response

  {
      "data": {
          "name": "Renamed",
          "billable": true,
          "workspace": {
              "name": "john.doe@gmail.com's workspace",
              "id": 31366 
          },
          "id": 279892,
          "fixed_fee": 0.0,
          "hourly_rate": 0.0,
          "is_fixed_fee": false,
          "client_project_name": "Another project",
          "estimated_workhours": 0,
          "automatically_calculate_estimated_workhours": true 
      },
      "related_data_updated_at": "2010-06-29T11:17:19+03:00" 
  }

Planned tasks

Get planned tasks

Example request

Example response

  {
      "data": [
          {
              "name": "Planned task",
              "workspace": {
                  "name": "john.doe@gmail.com's workspace",
                  "id": 31366
              },
              "id": 7140,
              "project": {
                  "name": "Important project",
                  "id": 279882
              },
              "user": {
                  "fullname": "Jane Doe",
                  "id": 104711
              },
              "estimated_workhours": 1
          }
      ],
      "related_data_updated_at": "2010-06-29T11:17:19+03:00"
  }

The "user" field may contain the users data who has been assigned with the planned task.

Tags

Get tags

Example request

Example response

  {
      "data": [
          {
              "name": "API",
              "workspace": {
                  "name": "john.doe@gmail.com's workspace",
                  "id": 31366
              },
              "id": 6414
          }
      ],
      "related_data_updated_at": "2010-06-29T11:17:19+03:00"
  }

Users

Get current user

Example request

Example response

  {
      "data": {
          "jquery_timeofday_format": "H:i",
          "api_token": "ffc3f3024ec5d40cee2e24d5ff023c12",
          "task_retention_days": 9,
          "jquery_date_format": "m/d/Y",
          "date_format": "%m/%d/%Y",
          "default_workspace_id": 31366,
          "new_tasks_start_automatically": true,
          "fullname": "John Doe",
          "language": "en_US",
          "id": 42182,
          "beginning_of_week": 1,
          "timeofday_format": "%H:%M",
          "email": "johndoe@gmail.com"
      },
      "related_data_updated_at": "2010-06-29T11:17:19+03:00"
  }

Get current user, including user's data

It is possible to get the user's tasks, projects, planned tasks, tags, workspaces and clients when requesting the current user's data. To do so, use the with_related_data optional parameter.

Example request

Example response

  {
      "data": {
          "jquery_timeofday_format": "H:i",
          "api_token": "ffc3f3024ec5d40cee2e24d5ff023c12",
          "task_retention_days": 9,
          "jquery_date_format": "m/d/Y",
          "date_format": "%m/%d/%Y",
          "default_workspace_id": 31366,
          "new_tasks_start_automatically": true,
          "fullname": "John Doe",
          "language": "en_US",
          "id": 42182,
          "beginning_of_week": 1,
          "timeofday_format": "%H:%M",
          "email": "johndoe@gmail.com",
          "clients": [
              {
                  "name": "Bart",
                  "workspace": {
                      "name": "john.doe@gmail.com's workspace",
                      "id": 31366 
                  },
                  "id": 105995,
                  "hourly_rate": 45.0,
                  "currency": "USD" 
              } 
          ],
          "projects": [
              {
                  "name": "Important stuff",
                  "billable": true,
                  "workspace": {
                      "name": "john.doe@gmail.com's workspace",
                      "id": 31366 
                  },
                  "id": 188909,
                  "fixed_fee": 0.0,
                  "hourly_rate": 45.0,
                  "is_fixed_fee": false,
                  "client_project_name": "Important stuff",
                  "estimated_workhours": 10 
              } 
          ],
          "planned_tasks": [
              {
                  "name": "Planned task",
                  "workspace": {
                      "name": "john.doe@gmail.com's workspace",
                      "id": 31366 
                  },
                  "id": 7140,
                  "project": {
                      "name": "Important project",
                      "id": 279882 
                  },
                  "user": {
                      "fullname": "Jane Doe",
                      "id": 104711 
                  },
                  "estimated_workhours": 1 
              } 
          ],
          "workspaces": [
              {
                  "name": "john.doe@gmail.com's workspace",
                  "id": 31366 
              } 
          ],
          "tags": [
              {
                  "name": "API",
                  "workspace": {
                      "name": "john.doe@gmail.com's workspace",
                      "id": 31366 
                  },
                  "id": 6414 
              } 
          ],
          "tasks": [
              {
                  "duration": -1265981479,
                  "billable": true,
                  "workspace": {
                      "name": "john.doe@gmail.com's workspace",
                      "id": 31366 
                  },
                  "stop": "2010-02-12T15:51:19+02:00",
                  "id": 2913477,
                  "project": {
                      "name": "Important project",
                      "id": 189657,
                      "client_project_name": "Important project" 
                  },
                  "start": "2010-02-12T15:35:47+02:00",
                  "tag_names": [
                      "API" 
                  ],
                  "description": "Today's task" 
              } 
          ] 
      },
      "related_data_updated_at": "2010-06-29T11:17:19+03:00"
  }

Code samples

Ruby

Koen Van der Auwera has written a wrapper for the Toggl API as a Ruby gem.

.NET

Mikael Lundin has written a series of blog posts on how to connect to Toggl API with .NET.

Android

The Toggl timer for Android is open source.