API
Freedom for developers
Toggl offers full access to its time tracking functionality through a webservice API.
This document is valid for Toggl version 1.13.2.
The API uses raw XML or JSON pushed over HTTP. All API calls support both XML and JSON.
You can determine the format of the request and response by setting the HTTP Accept: and Content-type: headers to application/json or application/xml.
All XML requests are composed of one request element which contains all the information of the request. JSON requests do not use a request element.
All XML responses are composed of one response element. Again, the JSON API does not need and does not use such an element.
Most responses will contain a content element. This is true for both the JSON and XML API.
During any API session you are required to accept and keep track of cookies. Cookies are set by the login request and must be provided as tokens of authentication to all other requests.
Timetracking
Tracked time is stored - in milliseconds - in the duration attribute of the task object. If the task is currently running, the duration attribute contains a negative value, denoting the start of the task in milliseconds since epoch (Jan 1 1970). The client is responsible for showing the correct duration to the user. The correct duration can be calculated as current_time + duration, where current_time is the current time (in milliseconds since epoch). The milliseconds since epoch must always be calculated in the GMT timezone.
Timezones
The client must supply a timezone to the server at login. This value is currently little used, but still necessary. It is part of an old timezone handling system that is being phased out as it is a common source of bugs.
All time values transmitted to the server, including values in milliseconds since epoch, must be in the GMT timezone. All time values contained in the responses of the server are likewise in the GMT timezone. The client is responsible for displaying the times to the user in an appropriate timezone.
Workspaces
Tasks and projects will be returned from all your workspaces in task and project lists.
Data Objects
Six different types of data objects can be transmitted through the API - user, task, planned task, project, client and workspace. Only tasks can be modified through the API; projects and clients can only be created; all other objects are read-only.
User
| confirm-close-task | - whether the client should ask for confirmation before closing tasks. Deprecated |
| date-format | - the user's preferred date format that the client should obey. |
| errors | - a list of validation failures. Present but not used (cannot save users). |
| fullname | - the full name of the user. |
| id | - the unique ID of the user. |
| new-tasks-start-automatically | - whether to start new tasks as they are created. The client is responsible for this. |
| stop-running-task-on-exit | - if this attribute is set, the client should inform the user if a task is left running after the client exits. |
| username | - the login name (username) of the user. |
| task-retention-days | - how many days old tasks should the client's GUI show. |
| timeofday-format | - the user's preferred format for the time of day, which the client should obey. |
| use-ssl | - whether the client should use SSL (https://) to connect to the server. |
Task
When creating a new task, the client should set the task's billable attribute to equal the project's billable attribute.
When closing a task, the client should only ask for confirmation if the logged in user's confirm-close-task attribute is set to true. Note that closing tasks is no longer necessary and all functionality pertaining to closing tasks is deprecated.
| billable | - whether the task is billable. |
| closed | - whether the task is closed (completed). Deprecated |
| description | - the description of the task. |
| duration | - the duration of the task, in milliseconds. Contains a negative value if the task is currently running (see Timetracking above) |
| errors | - a list of validation failures. Used in responses only. |
| id | - the unique ID of the task. Supply a negative ID (in the "/task/set" request) if you want to create a new task. |
| planned-task-id | - the ID of the associated planned task, if any. |
| planned-task-name | - the name of the associated planned task, if any. |
| project | - the associated project. |
| start-ms | - the start time of the task in milliseconds since epoch (in the GMT timezone). |
| stop-ms | - the time the task was stopped in milliseconds since epoch (in the GMT timezone). |
| tag-ids | - a list of the IDs of the associated tags. |
| workspace-id | - the ID of the associated workspace. |
The stop-ms attribute is set to 0 if not present. The client should show a blank in case stop-ms is 0. The client should never show Jan 1 1970 as the stop time.
Planned task
| errors | - a list of validation failures. Used in responses only. |
| id | - the unique ID of the planned task. |
| description | - the description of the planned task. |
| estimated-workhours | - the estimated duration of the planned task. |
| project | - the project the planned task belongs to. |
| workspace | - the workspace the planned task belongs to. |
Project
| billable | - whether new tasks for this project start out as billable. |
| client | - the attached client. |
| errors | - a list of validation failures. Used in responses only. |
| id | - the unique ID of the project. |
| name | - the name of the project. |
| workspace | - the associated workspace |
Client
| errors | - a list of validation failures. Used in responses only. |
| id | - the unique ID of the client. |
| name | - the name of the client. |
| workspace | - the workspace the client belongs to. |
Workspace
| errors | - a list of validation failures. Present but not used (cannot save workspaces). |
| id | - the unique ID of the workspace. |
| name | - the name of the workspace. |
Requests
All requests must supply a version parameter.
This will help retain backward compatibility.
Logging in
Send a POST request to "/user/login"
Supply tzoffset, user-login and user-password parameters.
| tzoffset | - timezone offset from GMT in seconds. |
| user-login | - the username (deprecated) or e-mail address of the user. |
| user-password | - the password of the user. |
If all goes well, the server will respond with a user.
{ "tzoffset": 0,
"user_login": "johndoe",
"user_password": "johndoe",
"version": "1.13.2"
}
{ "content":
[ { "confirm_close_task": true,
"date_format": "%d-%m-%Y",
"errors": [],
"fullname": "John Doe",
"id": 1,
"new_tasks_start_automatically": false,
"stop_running_task_on_exit": true,
"task_retention_days": 9,
"timeofday_format": "%I:%M %p",
"use_ssl": false,
"username": "johndoe"
}
],
"version": "1.13.2"
}
<?xml version="1.0" encoding="UTF-8"?>
<request>
<tzoffset type="integer">0</tzoffset>
<user-login>johndoe</user-login>
<user-password>johndoe</user-password>
<version>1.13.2</version>
</request>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<content type="array">
<user>
<confirm-close-task type="boolean">true</confirm-close-task>
<date-format>%d-%m-%Y</date-format>
<errors type="array"/>
<fullname>John Doe</fullname>
<id type="integer">1</id>
<new-tasks-start-automatically type="boolean">false</new-tasks-start-automatically>
<stop-running-task-on-exit type="boolean">true</stop-running-task-on-exit>
<task-retention-days type="integer">9</task-retention-days>
<timeofday-format>%I:%M %p</timeofday-format>
<use-ssl type="boolean">false</use-ssl>
<username>johndoe</username>
</user>
</content>
<version>1.13.2</version>
</response>
Listing all tasks between two dates
Send a GET or POST request to "/task/list".
This action lists tasks belonging to the logged in user.
Supply start_date_ms and end_date_ms parameters. These parameters must be milliseconds since epoch in the GMT timezone.
Due to historical reasons, the server adds 24 hours to the end_date_ms parameter. Therefore to list the tasks for one day, start_date_ms and end_date_ms should be equal. If you want to list tasks for less than one day, end_date_ms must be less than start_date_ms.
| start_date_ms | - the lower bound of the date range. |
| end_date_ms | - the upper bound of the date range. |
The response is a list of tasks, where each task contains a project, which itself contains a client, which contains a workspace.
{ "end_date_ms": 1143849600000,
"start_date_ms": 1141171200000,
"version": "1.13.2"
}
{ "content":
[ { "billable": true,
"closed": true,
"description": "launching a test rocket",
"duration": 900000,
"errors": [],
"id": 4,
"planned_task_id": 1,
"planned_task_name": "paint everything",
"project":
{ "billable": true,
"client":
{ "errors": [],
"id": 2,
"name": "Alien enterprise",
"workspace":
{ "errors": [],
"id": 2,
"name": "Krypton"
}
},
"errors": [],
"id": 2,
"name": "build a brand new spacecraft",
"workspace":
{ "errors": [],
"id": 2,
"name": "Krypton"
}
},
"start_ms": 1143019200000,
"stop_ms": 0,
"tag_ids": [],
"workspace_id": 2
}
],
"version": "1.13.2"
}
<?xml version="1.0" encoding="UTF-8"?>
<request>
<end-date-ms type="integer">1143849600000</end-date-ms>
<start-date-ms type="integer">1141171200000</start-date-ms>
<version>1.13.2</version>
</request>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<content type="array">
<task>
<billable type="boolean">true</billable>
<closed type="boolean">true</closed>
<description>launching a test rocket</description>
<duration type="integer">900000</duration>
<errors type="array"/>
<id type="integer">4</id>
<planned-task-id type="integer">1</planned-task-id>
<planned-task-name>paint everything</planned-task-name>
<project>
<billable type="boolean">true</billable>
<client>
<errors type="array"/>
<id type="integer">2</id>
<name>Alien enterprise</name>
<workspace>
<errors type="array"/>
<id type="integer">2</id>
<name>Krypton</name>
</workspace>
</client>
<errors type="array"/>
<id type="integer">2</id>
<name>build a brand new spacecraft</name>
<workspace>
<errors type="array"/>
<id type="integer">2</id>
<name>Krypton</name>
</workspace>
</project>
<start-ms type="integer">1143019200000</start-ms>
<stop-ms type="integer">0</stop-ms>
<tag-ids type="array"/>
<workspace-id type="integer">2</workspace-id>
</task>
</content>
<version>1.13.2</version>
</response>
Starting a new task
Send a POST request to "/task/set".
Supply a task as the parameter. The task must have a negative id attribute.
The task must contain a project with only an id attribute. As an alternative you can supply a project-id attribute within the task.
The server should respond with a task.
{ "task":
{ "duration": 123456,
"id": -1,
"project":
{ "id": 1
},
"start_ms": 1140060481000
},
"version": "1.13.2"
}
{ "content":
[ { "billable": true,
"closed": false,
"description": null,
"duration": 123456,
"errors": [],
"id": 25,
"planned_task_id": null,
"planned_task_name": null,
"project":
{ "billable": true,
"client":
{ "errors": [],
"id": 1,
"name": "Flower shop",
"workspace":
{ "errors": [],
"id": 1,
"name": "Earth"
}
},
"errors": [],
"id": 1,
"name": "doing stuff in garden",
"workspace":
{ "errors": [],
"id": 1,
"name": "Earth"
}
},
"start_ms": 1140060481000,
"stop_ms": 0,
"tag_ids": [],
"workspace_id": 1
}
],
"version": "1.13.2"
}
<?xml version="1.0" encoding="UTF-8"?>
<request>
<task>
<duration type="integer">123456</duration>
<id type="integer">-1</id>
<project>
<id type="integer">1</id>
</project>
<start-ms type="integer">1140060481000</start-ms>
</task>
<version>1.13.2</version>
</request>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<content type="array">
<task>
<billable type="boolean">true</billable>
<closed type="boolean">false</closed>
<description nil="true"></description>
<duration type="integer">123456</duration>
<errors type="array"/>
<id type="integer">25</id>
<planned-task-id nil="true"></planned-task-id>
<planned-task-name nil="true"></planned-task-name>
<project>
<billable type="boolean">true</billable>
<client>
<errors type="array"/>
<id type="integer">1</id>
<name>Flower shop</name>
<workspace>
<errors type="array"/>
<id type="integer">1</id>
<name>Earth</name>
</workspace>
</client>
<errors type="array"/>
<id type="integer">1</id>
<name>doing stuff in garden</name>
<workspace>
<errors type="array"/>
<id type="integer">1</id>
<name>Earth</name>
</workspace>
</project>
<start-ms type="integer">1140060481000</start-ms>
<stop-ms type="integer">0</stop-ms>
<tag-ids type="array"/>
<workspace-id type="integer">1</workspace-id>
</task>
</content>
<version>1.13.2</version>
</response>
Modifying an existing task
Send a POST request to "/task/set".
Supply a task as the parameter.
The server should respond with a task.
If you want to change the project of the task, supply either a project-id attribute or a project with an id attribute.
{ "task":
{ "description": "bla",
"duration": 123456,
"id": 1,
"project":
{ "id": 3
},
"start_ms": 1140060481000
},
"version": "1.13.2"
}
{ "content":
[ { "billable": true,
"closed": true,
"description": "bla",
"duration": 123456,
"errors": [],
"id": 1,
"planned_task_id": null,
"planned_task_name": null,
"project":
{ "billable": true,
"client": null,
"errors": [],
"id": 3,
"name": "delete this project",
"workspace":
{ "errors": [],
"id": 1,
"name": "Earth"
}
},
"start_ms": 1140060481000,
"stop_ms": 0,
"tag_ids": [],
"workspace_id": 1
}
],
"version": "1.13.2"
}
<?xml version=&quoe;quot;1.0" encoding="UTF-8"?>
<request>
<task>
<description>bla</description>
<duration type="integer">123456</duration>
<id type="integer">1</id>
<project>
<id type="integer">3</id>
</project>
<start-ms type="integer">1140060481000</start-ms>
</task>
<version>1.13.2</version>
</request>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<content type="array">
<task>
<billable type="boolean">true</billable>
<closed type="boolean">true</closed>
<description>bla</description>
<duration type="integer">123456</duration>
<errors type="array"/>
<id type="integer">1</id>
<planned-task-id nil="true"></planned-task-id>
<planned-task-name nil="true"></planned-task-name>
<project>
<billable type="boolean">true</billable>
<client nil="true"></client>
<errors type="array"/>
<id type="integer">3</id>
<name>delete this project</name>
<workspace>
<errors type="array"/>
<id type="integer">1</id>
<name>Earth</name>
</workspace>
</project>
<start-ms type="integer">1140060481000</start-ms>
<stop-ms type="integer">0</stop-ms>
<tag-ids type="array"/>
<workspace-id type="integer">1</workspace-id>
</task>
</content>
<version>1.13.2</version>
</response>
Deleting a task
Send a POST request to "/task/destroy".
Supply a task as the parameter. Only the id attribute need be set.
The server should respond with a string containing "success".
<?xml version="1.0" encoding="UTF-8"?>
<request>
<task>
<id type="integer">8</id>
</task>
<version>1.13.2</version>
</request>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<content>success</content>
<version>1.13.2</version>
</response>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<content>success</content>
<version>1.13.2</version>
</response>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>
<code>access_denied</code>
<message>You may not destroy the task</message>
</error>
<version>1.13.2</version>
</response>
Listing all projects
Send a GET or POST request to "/project/list".
No parameters other than "version" need to be supplied.
The response is a list of projects, where each project contains a client, which in turn contains a workspace.
{ "content":
[ { "billable": true,
"client":
{ "errors": [],
"id": 1,
"name": "Flower shop",
"workspace":
{ "errors": [], "id": 1,
"name": "Earth"
}
},
"errors": [],
"id": 1,
"name": "doing stuff in garden",
"workspace":
{ "errors": [],
"id": 1,
"name": "Earth"
}
},
{ "billable": true,
"client": null,
"errors": [],
"id": 3,
"name": "delete this project",
"workspace":
{ "errors": [],
"id": 1,
"name": "Earth"
}
}
],
"version": "1.13.2"
}
<?xml version="1.0" encoding="UTF-8"?>
<request>
<version>1.13.2</version>
</request>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<content type="array">
<project>
<billable type="boolean">true</billable>
<client>
<errors type="array"/>
<id type="integer">1</id>
<name>Flower shop</name>
<workspace>
<errors type="array"/>
<id type="integer">1</id>
<name>Earth</name>
</workspace>
</client>
<errors type="array"/>
<id type="integer">1</id>
<name>doing stuff in garden</name>
<workspace>
<errors type="array"/>
<id type="integer">1</id>
<name>Earth</name>
</workspace>
</project>
<project>
<billable type="boolean">true</billable>
<client nil="true"></client>
<errors type="array"/>
<id type="integer">3</id>
<name>delete this project</name>
<workspace>
<errors type="array"/>
<id type="integer">1</id>
<name>Earth</name>
</workspace>
</project>
</content>
<version>1.13.2</version>
</response>
Fetching one project
Send a GET or POST request to "/project/get".
Supply a project as the parameter. Only the id attribute need be set.
The response is a single project.
{ "content":
[ { "billable": true,
"client": null,
"errors": [],
"id": 3,
"name": "delete this project",
"workspace":
{ "errors": [],
"id": 1,
"name": "Earth"
}
}
],
"version": "1.13.2"
}
<?xml version="1.0" encoding="UTF-8"?>
<request>
<project>
<id type="integer">3</id>
</project>
<version>1.13.2</version>
</request>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<content type="array">
<project>
<billable type="boolean">true</billable>
<client nil="true"></client>
<errors type="array"/>
<id type="integer">3</id>
<name>delete this project</name>
<workspace>
<errors type="array"/>
<id type="integer">1</id>
<name>Earth</name>
</workspace>
</project>
</content>
<version>1.13.2</version>
</response>
Listing all clients
Send a GET or POST request to "/client/list".
No parameters other than "version" need to be supplied.
The response is a list of clients, where each client contains a workspace.
{ "content":
[ { "errors": [],
"id": 1,
"name": "Flower shop",
"workspace":
{ "errors": [],
"id": 1,
"name": "Earth"
}
},
{ "errors": [],
"id": 3,
"name": "omg",
"workspace":
{ "errors": [],
"id": 1,
"name": "Earth"
}
}
], "version": "1.13.2"
}
<?xml version="1.0" encoding="UTF-8"?>
<request>
<version>1.13.2</version>
</request>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<content type="array">
<client>
<errors type="array"/>
<id type="integer">1</id>
<name>Flower shop</name>
<workspace>
<errors type="array"/>
<id type="integer">1</id>
<name>Earth</name>
</workspace>
</client>
<client>
<errors type="array"/>
<id type="integer">3</id>
<name>omg</name>
<workspace>
<errors type="array"/>
<id type="integer">1</id>
<name>Earth</name>
</workspace>
</client>
</content>
<version>1.13.2</version>
</response>
Listing all workspaces
Send a GET or POST request to "/workspace/list".
No parameters other than "version" need to be supplied.
The response is a list of workspaces.
{ "content":
[ { "errors": [],
"id": 3,
"name": "Delete"
},
{ "errors": [],
"id": 1,
"name": "Earth"
}
],
"version": "1.13.2"
}
<?xml version="1.0" encoding="UTF-8"?>
<request>
<version>1.13.2</version>
</request>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<content type="array">
<workspace>
<errors type="array"/>
<id type="integer">3</id>
<name>Delete</name>
</workspace>
<workspace>
<errors type="array"/>
<id type="integer">1</id>
<name>Earth</name>
</workspace>
</content>
<version>1.13.2</version>
</response>
Listing all planned tasks
Send a GET or POST request to "/planned_task/list".
No parameters other than "version" need to be supplied.
The response is a list of planned tasks.
{ "content":
[ { "description": "paint everything",
"errors": [],
"estimated_workhours": 500,
"id": 1,
"project_id": 2
}
],
"version": "1.13.2"
}
<?xml version="1.0" encoding="UTF-8"?>
<request>
<version>1.13.2</version>
</request>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<content type="array">
<planned-task>
<description>paint everything</description>
<errors type="array"/>
<estimated-workhours type="integer">500</estimated-workhours>
<id type="integer">1</id>
<project-id type="integer">2</project-id>
</planned-task>
</content>
<version>1.13.2</version>
</response>
Creating a new project
Send a POST request to "/project/create_from_api".
Supply a project as the parameter. The project must contain a client with an id attribute.
The server should respond with a project.
{ "project":
{ "billable": true,
"client":
{ "id": 1
},
"name": "testing project create"
},
"version": "1.13.2"
}
{ "content":
[ { "billable": true,
"client":
{ "errors": [],
"id": 1,
"name": "Flower shop",
"workspace":
{ "errors": [],
"id": 1,
"name": "Earth"
}
},
"errors": [],
"id": 7,
"name": "testing project create",
"workspace":
{ "errors": [],
"id": 1,
"name": "Earth"
}
}
],
"version": "1.13.2"
}
<?xml version="1.0" encoding="UTF-8"?>
<request>
<project>
<billable type="boolean">true</billable>
<client>
<id type="integer">1</id>
</client>
<name>testing project create</name>
</project>
<version>1.13.2</version>
</request>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<content type="array">
<project>
<billable type="boolean">true</billable>
<client>
<errors type="array"/>
<id type="integer">1</id>
<name>Flower shop</name>
<workspace>
<errors type="array"/>
<id type="integer">1</id>
<name>Earth</name>
</workspace>
</client>
<errors type="array"/>
<id type="integer">7</id>
<name>testing project create</name>
<workspace>
<errors type="array"/>
<id type="integer">1</id>
<name>Earth</name>
</workspace>
</project>
</content>
<version>1.13.2</version>
</response>
Creating a new client
Send a POST request to "/client/create_from_api".
Supply a client as the parameter. The client must contain a workspace with an id attribute.
The server should respond with a client.
{ "client":
{ "name": "testing client create",
"workspace":
{ "id": 1
}
},
"version": "1.13.2"
}
{ "content":
[ { "errors": [],
"id": 6,
"name": "testing client create",
"workspace":
{ "errors": [],
"id": 1,
"name": "Earth"
}
}
],
"version": "1.13.2"
}
<?xml version="1.0" encoding="UTF-8"?>
<request>
<client>
<name>testing client create</name>
<workspace>
<id type="integer">1</id>
</workspace>
</client>
<version>1.13.2</version>
</request>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<content type="array">
<client>
<errors type="array"/>
<id type="integer">6</id>
<name>testing client create</name>
<workspace>
<errors type="array"/>
<id type="integer">1</id>
<name>Earth</name>
</workspace>
</client>
</content>
<version>1.13.2</version>
</response>
Logging out
Send a POST request to "/user/logout"
No parameters other than "version" need to be supplied.
<?xml version="1.0" encoding="UTF-8"?>
<request>
<version>1.13.2</version>
</request>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<content>success</content>
<version>1.13.2</version>
</response>