Toggl.com API description
This document is valid for Toggl versions 0.12.0 to 0.12.1 at least.
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 text/json or text/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.
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).
Timezones
The client must supply a timezone to the server at login. All time values transmitted to the server will be interpreted as having the timezone supplied at login, even if there is a different timezone attached to the transmitted time value.
We are considering rewriting the timezone handling system as it is a major source of bugs.
Workspaces
The API doesn't differentiate between workspaces. In task and project lists tasks and projects will be returned from all your workspaces.
Data Objects
Four different types of data objects can be transmitted through the API - user, task, project and client. Only task objects can be modified through the API; all other objects are read-only.
User
Attributes:
| confirm-close-task | - whether the client should ask for confirmation before closing tasks. |
| 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. |
| username | - the login name (username) of the user. |
Task
When creating a new task, the client should set the task's billable attribute the same as 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.
Attributes:
| billable | - whether the task is billable. |
| closed | - whether the task is closed (completed). |
| description | - the description of the task./td>
|
| 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 if you want to start a new task. |
| project | - the associated project. Used in responses only. |
| project_id | - the ID of the associated project. Used in requests only. |
| start_as_plaintext | - the start date of the task in YYYY-MM-DD format. |
Project
Attributes:
| billable | - whether new tasks for this project start out as billable. |
| client | - the attached client object. |
| errors | - a list of validation failures. Present but not used (cannot save projects). |
| id | - the unique ID of the project. |
| name | - the name of the project. |
| team | - the team of the project (a space-separated list) |
Client
Attributes:
| errors | - a list of validation failures. Present but not used (cannot save clients). |
| id | - the unique ID of the client. |
| name | - the name of the client. |
Requests
All requests must supply a version parameter.
This will help retain backward compatibility.
Logging in
Send a POST request to "http://www.toggl.com/user/login"
Supply tzoffset, user_login and user_password parameters.
| tzoffset | - timezone offset from GMT in seconds. |
| user_login | - the username (login name) of the user. |
| user_password | - the password of the user. |
If all goes well, the server will respond with a user object.
Example JSON Request
{"tzoffset":0,"user_login":"johndoe","user_password":"johndoe","version":"0.12.0"}
Example JSON Response
{"content":[{"confirm_close_task":true,"errors":[],"fullname":"John Doe","id":1,"username":"johndoe"}],"version":"0.12.0"}
Example XML Request
<?xml version="1.0" encoding="UTF-8"?>
<request>
<version>0.12.0</version>
<tzoffset>0</tzoffset>
<user_login>johndoe@gmail.com</user_login>
<user_password>johndoe</user_password>
</request>
Example XML Response
<?xml version="1.0" encoding="UTF-8"?>
<response>
<content>
<user>
<confirm-close-task type="boolean">true</confirm-close-task>
<errors>
</errors>
<fullname>John Doe</fullname>
<id type="integer">1</id>
<username>johndoe</username>
</user>
</content>
<version>0.12.0</version>
</response>
Listing all open tasks
Send a GET or POST request to "http://www.toggl.com/task/list_open".
No parameters other than "version" need be supplied.
The response is a list of task objects, where each task contains a project object which itself contains a client object.
Example JSON Request
{"version":"0.12.0"}
Example JSON Response
{ "content":
[ { "billable":true,
"closed":false,
"description":"confirmed on close",
"duration":7200000,
"errors":[],
"id":6,
"project":
{ "billable":true,
"client":
{ "errors":[],
"id":1,
"name":"Flower shop"
},
"errors":[],
"id":1,
"name":"doing stuff in garden",
"team":"jane, johndoe, johnsmith"
},
"start_as_plaintext":"2006-03-20"
},
{ "billable":true,
"closed":false,
"description":null,
"duration":7200000,
"errors":[],
"id":8,
"project":
{ "billable":true,
"client":
{ "errors":[],
"id":1,
"name":"Flower shop"
},
"errors":[],
"id":1,
"name":"doing stuff in garden",
"team":"jane, johndoe, johnsmith"
},
"start_as_plaintext":"2006-03-20"
}
],
"version":"0.12.0"
}
Example XML Request
<?xml version="1.0" encoding="UTF-8"?>
<request>
<version>0.12.0</version>
</request>
Example XML Response
<?xml version="1.0" encoding="UTF-8"?>
<response>
<content>
<task>
<billable type="boolean">true</billable>
<closed type="boolean">false</closed>
<description>confirmed on close</description>
<duration type="integer">7200000</duration>
<errors>
</errors>
<id type="integer">6</id>
<project>
<billable type="boolean">true</billable>
<client>
<errors>
</errors>
<id type="integer>1</id>
<name>Flower shop</name>
</client>
<errors>
</errors>
<id type="integer">1</id>
<name>doing stuff in garden</name>
<team>jane, johndoe, johnsmith</team>
</project>
<start-as-plaintext>2006-03-20</start-as-plaintext>
</task>
<task>
<billable type="boolean">true</billable>
<closed type="boolean">false</closed>
<description nil="true"></description>
<duration type="integer"7200000</duration>
<errors>
</errors>
<id type="integer">8</id>
<project>
<billable type="boolean">true</billable>
<client>
<errors>
</errors>
<id type="integer">1</id>
<name>Flower shop</name>
</client>
<errors>
</errors>
<id type="integer">1</id>
<name>doing stuff in garden</name>
<team>jane, johndoe, johnsmith</team>
</project>
<start-as-plaintext>2006-03-20</start-as-plaintext>
</task>
</content>
<version>0.12.0</version>
</response>
Listing all tasks between two dates
Send a GET or POST request to "http://www.toggl.com/task/list".
Supply start_date and end_date parameters.
| start_date | - the lower bound of the date range. |
| end_date | - the upper bound of the date range. |
The response is a list of task objects, where each task contains a project object which itself contains a client object.
The response contains both open and closed tasks.
Example JSON Request
{"end_date":"01-04-2006","start_date":"01-03-2006","version":"0.12.0"}
Example JSON Response
{ "content":
[ { "billable":true,
"closed":true,
"description":"launching a test rocket",
"duration":900000,
"errors":[],
"id":4,
"project":
{ "billable":true,
"client":
{ "errors":[],
"id":2,
"name":"Alien enterprise"
},
"errors":[],
"id":2,
"name":"build a brand new spacecraft",
"team":"clark, jane, johnsmith"
},
"start_as_plaintext":"2006-03-22"
}
],
"version":"0.12.0"
}
Example XML Request
<?xml version="1.0" encoding="UTF-8"?>
<request>
<end-date>01-04-2006</end-date>
<start-date>01-03-2006</start-date>
<version>0.12.0</version>
</request>
Example XML Response
<?xml version="1.0" encoding="UTF-8"?>
<response>
<content>
<task>
<billable type="boolean">true</billable>
<closed type="boolean">true</closed>
<description>launching a test rocket</description>
<duration type="integer">900000</duration>
<errors>
</errors>
<id type="integer">4</id>
<project>
<billable type="boolean">true</billable>
<client>
<errors>
</errors>
<id type="integer">2</id>
<name>Alien enterprise</name>
</client>
<errors>
</errors>
<id type="integer">2</id>
<name>build a brand new spacecraft</name>
<team>clark, jane, johnsmith</team>
</project>
<start-as-plaintext>2006-03-22</start-as-plaintext>
</task>
</content>
<version>0.12.0</version>
</response>
Starting a new task
Send a POST request to "http://www.toggl.com/task/set".
Supply a task object as a parameter. The task object must have a negative id attribute.
The server should respond with a task object.
Example JSON request
{ "task":
{ "duration":123456,
"id":-1,
"project_id":1,
"start":"Thu Feb 16 03:28:01 2006"
},
"version":"0.12.0"
}
Example JSON response
{ "content":
[ { "billable":true,
"closed":false,
"description":null,
"duration":123456,
"errors":[],
"id":11,
"project":
{ "billable":true,
"client":
{ "errors":[],
"id":1,
"name":"Flower shop"
},
"errors":[],
"id":1,
"name":"doing stuff in garden",
"team":"jane, johndoe, johnsmith"
},
"start_as_plaintext":"2007-06-18"
}
],
"version":"0.12.0"
}
Example XML request
<?xml version="1.0" encoding="UTF-8"?>
<request>
<task>
<duration type="integer">123456</duration>
<id type="integer">-1</id>
<project-id type="integer">1</project-id>
<start type="datetime">2006-02-16T03:28:01Z</start>
</task>
<version>0.12.0</version>
</request>
Example XML response
<?xml version="1.0" encoding="UTF-8"?>
<response>
<content>
<task>
<billable type="boolean">true</billable>
<closed type="boolean">false</closed>
<description nil="true"></description>
<duration type="integer">123456</duration>
<errors>
</errors>
<id type="integer">11</id>
<project>
<billable type="boolean">true</billable>
<client>
<errors>
</errors>
<id type="integer">1</id>
<name>Flower shop</name>
</client>
<errors>
</errors>
<id type="integer">1</id>
<name>doing stuff in garden</name>
<team>jane, johndoe, johnsmith</team>
</project>
<start-as-plaintext>2007-06-18</start-as-plaintext>
</task>
</content>
<version>0.12.0</version>
</response>
Modifying an existing task
Send a POST request to "http://www.toggl.com/task/set".
Supply a task object as a parameter.
The server should respond with a task object.
Use this request to close tasks - just supply a true in the closed attribute.
If you want to change the project of the task, supply a project_id attribute. Never supply a full project object in a project attribute when performing a request.
Example JSON request
{ "task":
{ "closed":true,
"description":"bla",
"duration":123456,
"id":1,
"project_id":1,
"start":"Thu Feb 16 03:28:01 2006"
},
"version":"0.12.0"
}
Example JSON response
{ "content":
[ { "billable":true,
"closed":true,
"description":"bla",
"duration":123456,
"errors":[],
"id":1,
"project":
{ "billable":true,
"client":
{ "errors":[],
"id":1,
"name":"Flower shop"
},
"errors":[],
"id":1,
"name":"doing stuff in garden",
"team":"jane, johndoe, johnsmith"
},
"start_as_plaintext":"2006-02-16"
}
],
"version":"0.12.0"
}
Example XML request
<?xml version="1.0" encoding="UTF-8"?>
<request>
<task>
<closed type="boolean">true</closed>
<description>bla</description>
<duration type="integer">123456</duration>
<id type="integer">1</id>
<project-id type="integer">1</project-id>
<start type="datetime">2006-02-16T03:28:01Z</start>
</task>
<version>0.12.0</version>
</request>
Example XML response
<?xml version="1.0" encoding="UTF-8"?>
<response>
<content>
<task>
<billable type="boolean">true</billable>
<closed type="boolean">true</closed>
<description>bla</description>
<duration type="integer">123456</duration>
<errors>
</errors>
<id type="integer">1</id>
<project>
<billable type="boolean">true</billable>
<client>
<errors>
</errors>
<id type="integer">1</id>
<name>Flower shop</name>
</client>
<errors>
</errors>
<id type="integer">1</id>
<name>doing stuff in garden</name>
<team>jane, johndoe, johnsmith</team>
</project>
<start-as-plaintext>2006-02-16</start-as-plaintext>
</task>
</content>
<version>0.12.0</version>
</response>
Deleting a task
Send a POST request to "http://www.toggl.com/task/destroy".
Supply a task object as a parameter. Only the id attribute need be set.
The server should respond with a string containing "success".
Example JSON request
{"task":{"id":8},"version":"0.12.0"}
Example JSON response
{"content":"success","version":"0.12.0"}
Example XML request
<?xml version="1.0" encoding="UTF-8"?>
<request>
<task>
<id type="integer">8</id>
</task>
<version>0.12.0</version>
</request>
Example XML response
<?xml version="1.0" encoding="UTF-8"?>
<response>
<content>success</content>
<version>0.12.0</version>
</response>
Listing all projects
Send a GET or POST request to "http://www.toggl.com/project/list".
No parameters other than "version" need be supplied.
The response is a list of project objects, where each project contains a client object.
Example JSON request
{"version":"0.12.0"}
Example JSON response
{ "content":
[ { "billable":true,
"client":
{ "errors":[],
"id":1,
"name":"Flower shop"
},
"errors":[],
"id":3,
"name":"delete this project",
"team":"johndoe"
},
{ "billable":true,
"client":
{ "errors":[],
"id":1,
"name":"Flower shop"
},
"errors":[],
"id":1,
"name":"doing stuff in garden",
"team":"jane, johndoe, johnsmith"
}
],
"version":"0.12.0"
}
Example XML request
<?xml version="1.0" encoding="UTF-8"?>
<request>
<version>0.12.0</version>
</request>
Example XML response
<?xml version="1.0" encoding="UTF-8"?>
<response>
<content>
<project>
<billable type="boolean">true</billable>
<client>
<errors>
</errors>
<id type="integer">1</id>
<name>Flower shop</name>
</client>
<errors>
</errors>
<id type="integer">3</id>
<name>delete this project</name>
<team>johndoe</team>
</project>
<project>
<billable type="boolean">true</billable>
<client>
<errors>
</errors>
<id type="integer">1</id>
<name>Flower shop</name>
</client>
<errors>
</errors>
<id type="integer">1</id>
<name>doing stuff in garden</name>
<team>jane, johndoe, johnsmith</team>
</project>
</content>
<version>0.12.0</version>
</response>
Fetching one project
Send a GET or POST request to "http://www.toggl.com/project/get".
Supply a project object as a parameter. Only the id attribute need be set.
The response is a single project object.
Example JSON request
{"project":{"id":3},"version":"0.12.0"}
Example JSON response
{ "content":
[ { "billable":true,
"client":
{ "errors":[],
"id":1,
"name":"Flower shop"
},
"errors":[],
"id":3,
"name":"delete this project",
"team":"johndoe"
}
],
"version":"0.12.0"
}
Example XML request
<?xml version="1.0" encoding="UTF-8"?>
<request>
<project>
<id type="integer">3</id>
</project>
<version>0.12.0</version>
</request>
Example XML response
<?xml version="1.0" encoding="UTF-8"?>
<response>
<content>
<project>
<billable type="boolean">true</billable>
<client>
<errors>
</errors>
<id type="integer">1</id>
<name>Flower shop</name>
</client>
<errors>
</errors>
<id type="integer">3</id>
<name>delete this project</name>
<team>johndoe</team>
</project>
</content>
<version>0.12.0</version>
</response>
Logging out
Send a POST request to "http://www.toggl.com/user/logout"
No parameters other than "version" need be supplied.
Example JSON request
{"version":"0.12.0"}
Example JSON response
{"content":"success","version":"0.12.0"}
Example XML request
<?xml version="1.0" encoding="UTF-8"?> <request> <version>0.12.0</version> </request>
Example XML response
<?xml version="1.0" encoding="UTF-8"?>
<response>
<content>success</content>
<version>0.12.0</version>
</response>