Toggl API
Introduction
Toggl provides a simple REST-style JSON API over standard HTTP.
The result of each action is communicated via standard HTTP response codes. If a create or update action failed, HTTP status code 400 and an array of localized error messages will be returned.
Example request
curl -u 1971800d4d82861d8f2c1651fea4d212:api_token -H "Content-type: application/json" -d "{\"task\":{\"description\":\"New task\",\"created_with\":\"API example code\"}}" -X POST http://www.toggl.com/api/v1/tasks.json
Example response
["Start can't be blank"]
To make eavesdropping of messages between you and Toggl harder, we suggest using HTTPS instead of plain HTTP.
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
curl -d email=john.doe@gmail.com -d password=secret -X POST http://www.toggl.com/api/v1/sessions.json
Example response
{"jquery_timeofday_format"=>"H:i", "api_token"=>"ffc3f3024ec5d40cee2e24d5ff023c12", "task_retention_days"=>9, "jquery_date_format"=>"m/d/Y", "utc_offset"=>-18000, "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"}
HTTP POST with API token
Example request
curl -d api_token=1971800d4d82861d8f2c1651fea4d212 -X POST http://www.toggl.com/api/v1/sessions.json
Example response
{"jquery_timeofday_format"=>"H:i", "api_token"=>"ffc3f3024ec5d40cee2e24d5ff023c12", "task_retention_days"=>9, "jquery_date_format"=>"m/d/Y", "utc_offset"=>-18000, "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"}
HTTP Basic Auth with e-mail and password
Example request
curl -u john.doe@gmail.com:secret -X GET http://www.toggl.com/api/v1/me.json
Example response
{"jquery_timeofday_format"=>"H:i", "api_token"=>"ffc3f3024ec5d40cee2e24d5ff023c12", "task_retention_days"=>9, "jquery_date_format"=>"m/d/Y", "utc_offset"=>-18000, "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"}
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
curl -u 1971800d4d82861d8f2c1651fea4d212:api_token -X GET http://www.toggl.com/api/v1/me.json
Example response
{"jquery_timeofday_format"=>"H:i", "api_token"=>"ffc3f3024ec5d40cee2e24d5ff023c12", "task_retention_days"=>9, "jquery_date_format"=>"m/d/Y", "utc_offset"=>-18000, "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"}
Tasks
Get tasks
Example request
curl -u 1971800d4d82861d8f2c1651fea4d212:api_token -X GET http://www.toggl.com/api/v1/tasks.json
Example response
[{"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"}]
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
curl -u 1971800d4d82861d8f2c1651fea4d212:api_token -d start_date=2010-02-05T15:42:46+02:00 -d end_date=2010-02-12T15:42:46+02:00 -X GET http://www.toggl.com/api/v1/tasks.json
Example response
[{"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"=>"Today's task"}]
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
curl -u 1971800d4d82861d8f2c1651fea4d212:api_token -H "Content-type: application/json" -d "{\"task\":{\"tag_names\":[\"API\"],\"billable\":true,\"workspace\":{\"id\":31366},\"description\":\"A new task\",\"start\":\"2010-02-12T16:19:45+02:00\",\"duration\":900,\"created_with\":\"Ruby example code\",\"project\":{\"id\":2913477}}}" -X POST http://www.toggl.com/api/v1/tasks.json
Example response
{"duration"=>900, "billable"=>true, "workspace"=>{"name"=>"john.doe@gmail.com's workspace", "id"=>31366}, "stop"=>nil, "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"}
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
curl -u 1971800d4d82861d8f2c1651fea4d212:api_token -H "Content-type: application/json" -d "{\"task\":{\"tag_names\":[\"API\", \"Example\"],\"billable\":true,\"workspace\":{\"id\":31366},\"description\":\"Name changed\",\"start\":\"2010-02-12T16:19:45+02:00\",\"duration\":900,\"project\":{\"id\":189657}}}" -X PUT http://www.toggl.com/api/v1/tasks/2913477.json
Example response
{"duration"=>1800, "billable"=>true, "workspace"=>{"name"=>"john.doe@gmail.com's workspace", "id"=>31366}, "stop"=>nil, "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"}
Destroy a task
Example request
curl -u 1971800d4d82861d8f2c1651fea4d212:api_token -X DELETE http://www.toggl.com/api/v1/tasks/2913477.json
Workspaces
Get workspaces
Example request
curl -u 1971800d4d82861d8f2c1651fea4d212:api_token -X GET http://www.toggl.com/api/v1/workspaces.json
Example response
[{"name"=>"john.doe@gmail.com's workspace", "id"=>31366}]
Clients
Get clients
Example request
curl -u 1971800d4d82861d8f2c1651fea4d212:api_token -X GET http://www.toggl.com/api/v1/clients.json
Example response
[{"name"=>"Bart", "workspace"=>{"name"=>"john.doe@gmail.com's workspace", "id"=>31366}, "id"=>105995, "hourly_rate"=>45.0, "currency"=>"USD"}]
Projects
Get projects
Example request
curl -u 1971800d4d82861d8f2c1651fea4d212:api_token -X GET http://www.toggl.com/api/v1/projects.json
Example response
[{"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}]
The "client_project_name" field is for convenience and renders both the client name and project name.
Create a new project
Example request
curl -u 1971800d4d82861d8f2c1651fea4d212:api_token -H "Content-type: application/json" -d "{\"project\":{\"billable\":true,\"workspace\":{\"id\":31366},\"name\":\"Another project\"}}" -X POST http://www.toggl.com/api/v1/projects.json
Example response
{"name"=>"Another project", "billable"=>true, "workspace"=>{"name"=>"john.doe@gmail.com's workspace", "id"=>31366}, "id"=>279892, "fixed_fee"=>0.0, "hourly_rate"=>nil, "is_fixed_fee"=>false, "client_project_name"=>"Another project", "estimated_workhours"=>nil}
Planned tasks
Get planned tasks
Example request
curl -u 1971800d4d82861d8f2c1651fea4d212:api_token -X GET http://www.toggl.com/api/v1/planned_tasks.json
Example response
[{"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}]
The "user" field may contain the users data who has been assigned with the planned task.
Tags
Get tags
Example request
curl -u 1971800d4d82861d8f2c1651fea4d212:api_token -X GET http://www.toggl.com/api/v1/tags.json
Example response
[{"name"=>"API", "workspace"=>{"name"=>"john.doe@gmail.com's workspace", "id"=>31366}, "id"=>6414}]
Users
Get current user
Example request
curl -u 1971800d4d82861d8f2c1651fea4d212:api_token -X GET http://www.toggl.com/api/v1/me.json
Example response
{"jquery_timeofday_format"=>"H:i", "api_token"=>"ffc3f3024ec5d40cee2e24d5ff023c12", "task_retention_days"=>9, "jquery_date_format"=>"m/d/Y", "utc_offset"=>-18000, "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"}