Toodledo
 An easy to use, online to-do list. Get organized, stay motivated, and be more productive.
Made something cool?

If you make something cool with this API, please let us know so that we can help spread the word.


Ruby API/Client - Made by Will Sargent

C# .NET library - Made by Doug Reichard

Perl Module - Made by Peter Scott

Java - Made by Marc

Developer's API Documentation

The Toodledo API makes it easy for developers to interact with their tasks and make new and interesting applications.

The Toodledo API uses a REST interface. REST is a simple format that allows you to make queries by constructing a URL and making an HTTP GET or POST. The server responds with an XML document containing the information that you requested.


iFrame

If you just want a quick way to integrate Toodledo into your web app, you might consider using an iFrame of our "Slim" website. Our "Slim" website is optimized for small windows and works great inside an iFrame.

http://www.toodledo.com/slim

<iframe src="http://www.toodledo.com/slim" width="250" height="300"></iframe>

Authentication

In order to insure that your data remains safe, all API calls must use authentication. You will need to know your userid and your password to authenticate yourself.

Your unique userid: [Please signin first]

You will need to make the following api call before starting a session:

api.toodledo.com/api.php?method=getToken;userid=YourUserID

In return you will get a token.

<token>td12345678901234</token>

This token is good for 4 hours. At the end of four hours, you will need to get a new token. You should cache the token so that you don't have to get a token for every API call. The token will be used to generate a key. The key is generated by using an MD5 hash like so:

PHP: $key = md5(  md5($mypassword).$token.$myuserid );
C: key = md5( md5(password)+token+myuserid );

This key must be sent in all future API calls to authenticate yourself.

If you are having trouble authenticating, make sure you notice that your password is hashed once before you concatenate it with the other variables, and then the entire thing is hashed again. Also, make sure your md5 function is returning a 32 character hexadecimal string. To test your md5 function, we would expect the md5 hash of the string "test" to be 098f6bcd4621d373cade4e832627b4f6.


Application ID

When requesting a token, you can optionally pass an application identifier. This will allow us to track the popularity of different applications and help us monitor and improve our API. An application id is an alphanumeric string up to 32 characters long. Example: 

api.toodledo.com/api.php?method=getToken;userid=YourUserID;appid=myappid

It is only necessary to pass the appid when requesting a token. We'll keep track of all requests made with the same token. Your AppID may be displayed to your customers on our website, so pick something that is readable.


Synchronization

If you are building an application that intends to synchronize with Toodledo, please read this section for suggestions about how to do this efficiently.

The first thing that your application should do is to use the "getServerInfo" API call to fetch the current server time. You can also call "getAccountInfo" to fetch the user's timezone. These two numbers can be used to synchronize your application's clock to Toodledo's clock. This will be very important when you are comparing timestamps to determine if a task has been modified.

Each time you attempt a synchronization, your application should use the "getAccountInfo" API call. This will return two timestamps which you can use to determine if any further action is needed. The "lastaddedit" timestamp will indicate if any task has been added or edited. If this value has changed since the last time you checked, you can call "getTasks" and set the "modafter" parameter to fetch the tasks that have changed. The "lastdelete" timestamp will indicate if any tasks have been deleted. If this value has changed since you last checked, you can call "getDeleted" and set the "after" parameter to fetch the tasks that have been deleted from Toodledo.

There are 7 scenarios that your application must deal with when synchronizing with Toodledo.

  1. Task added in your application
  2. Task edited in your application
  3. Task deleted in your application
  4. Task added on Toodledo
  5. Task edited on Toodledo
  6. Task deleted on Toodledo
  7. Task edited on both Toodledo and your application

For scenarios 1,2 and 3, your application will need to use the "addTask", "editTask" or "deleteTask" API calls to add/edit/delete the task. Adding and Deleting can be done without checking, but before you edit a task, you should first fetch it and compare the modification dates to make sure you are not overwriting a more recent version of the task. For scenarios 4,5 and 6, your application will need to use the "getTasks" and "getDeleted" API calls to fetch the updated information. For scenario 7, your application will have to compare modification dates and determined that the task has been updated in both places. Your application should prompt the user and ask them which version of the task they want to keep.


Rate Limiting

Each authenticated user is allowed to make 120 requests per 60 minute time period (2 per minute). If you cache your data properly, this should be more than enough for any application.

If you make more than 120 requests in a 60 minute period, any further requests will generate an error message until the request/hour drops below 120.


Retrieving Tasks

The "getTasks" API call will return a list of the tasks that match your search parameters. The following search parameters may be set.

http://api.toodledo.com/api.php?method=getTasks;key=YourKey;shorter=130;
longer=10;priority=2;end=2

This returns a list of tasks that might look something like this.

<tasks num="2" total="45" start="0" end="2">
	<task>
		<id>1234</id>
		<parent>1122</parent>
		<children>0</children>
		<title>Buy Milk</title>
		<tag>After work</tag>
		<folder>123</folder>
		<context id="123">Home</context>
		<goal id="123">Get a Raise</goal>
		<added>2006-01-23</added>
		<modified>2006-01-25 05:12:45</modified>
		<startdate></startdate>
		<duedate modifier=""></duedate>
		<duetime>2:00pm</duetime>
		<starttime>1:00pm</starttime>
		<completed></completed>
		<repeat>1</repeat>
		<rep_advanced></rep_advanced>
		<status>4</status>
		<star>0</star>
		<priority>2</priority>
		<length>20</length>
		<timer onfor="0">0</timer>
		<note></note>
	</task>
	<task>
		<id>1235</id>
		<parent>0</parent>
		<children>2</children>
		<title>Fix flat tire</title>
		<tag>before work</tag>
		<folder>456</folder>
		<context id="0"></context>
		<goal id="0"></goal>
		<added>2006-01-23</added>
		<modified>2006-01-23 15:45:55</modified>
		<startdate>2009-07-02</startdate>
		<duedate modifier="=">2009-07-02</duedate>
		<duetime>9:45am</duetime>
		<starttime>4:45am</starttime>
		<completed>2009-07-02</completed>
		<repeat>50</repeat>
		<rep_advanced>Every Monday</rep_advanced>
		<status>2</status>
		<star>1</star>
		<priority>2</priority>
		<length>120</length>
		<timer onfor="123">600</timer>
		<note>Use the car jack</note>
	</task>
</tasks>

Most of the returned values should be self explanatory with a few exceptions. The value of the "repeat" field may have some special values. Values 0-9 will match the values listed above, but it can also have the value of 50, which indicates that the task uses advanced repeating. If this is the case, you will need to look at the "rep_advanced" field. Additionally, if the task is set to repeat from the completion date (instead of the original due-date), the repeat value will be incremented by 100. For example, a repeat value of 2 means repeat monthly from the due-date and a value of 102 means repeat monthly from the completion date.

The timer field also needs a little explanation. The value in the timer field indicates the number of seconds that have elapsed for the timer not including the current session. If the timer is currently on, the "onfor" value will contain a unix timestamp indicating the last time that the timer was started. Therefore, if the timer is currently on, you will need to calculate the elapsed time when you present it to the user. This calculation is: Total Time=timer+(now-onfor). Where "now" is a unix timestamp for the current time in Toodledo's timezone (which can be found with the "getServerInfo" API call).

"num" is the number of tasks in the current result set. "total" is the total number of tasks that would match your query if you did not use the "start" and "end" paramaters to paginate your results.


Retrieving Folders

The "getFolders" API call will return a list of your folders with their names and id numbers. The id numbers are necessary for editing folders and adding or editing tasks. The 'private' and 'archived' boolean values reflect their settings. The 'order' integer represents the user's prefered order for listing folders.

http://api.toodledo.com/api.php?method=getFolders;key=YourKey

This call will return something that looks like this.

<folders>
	<folder id="123" private="0" archived="0" order="1">Shopping</folder>
	<folder id="456" private="0" archived="0" order="2">Home Repairs</folder>
	<folder id="789" private="0" archived="0" order="3">Vacation Planning</folder>
	<folder id="234" private="0" archived="0" order="4">Chores</folder>
	<folder id="567" private="1" archived="0" order="5">Work</folder>
</folders>

Retrieving Contexts

The "getContexts" API call will return a list of your contexts with their names and id numbers. The id numbers are necessary for adding or editing tasks.

http://api.toodledo.com/api.php?method=getContexts;key=YourKey

This call will return something that looks like this.

<contexts>
	<context id="123">Work</context>
	<context id="456">Home</context>
	<context id="789">Car</context>
</contexts>

Retrieving Goals

The "getGoals" API call will return a list of your goals with their names, id numbers, level (0=lifetime, 1=long-term, 2=short-term), and whether they contribute to other goals. The id numbers are necessary for adding or editing tasks.

http://api.toodledo.com/api.php?method=getGoals;key=YourKey

This call will return something that looks like this.

<goals>
	<goal id="123" level="0" contributes="0" archived="1">Get a Raise</goal>
	<goal id="456" level="0" contributes="0" archived="0">Lose Weight</goal>
	<goal id="789" level="1" contributes="456" archived="0">Exercise regularly</goal>
</goals>

Adding Tasks

You can easily add a task to your list with the "addTask" API call. The title field is required, but all other fields are optional.

http://api.toodledo.com/api.php?method=addTask;key=YourKey;
title=new years;priority=1;repeat=0;length=30;duedate=2010-01-01

If the add was successful the id number of the new task will be returned.

<added>12345</added>

Adding Folders

Add a folder using the "addFolder" API call. The title field is required, and the private field is optional.

http://api.toodledo.com/api.php?method=addFolder;key=YourKey;title=MyFold;private=1

If the add was successful the id number of the new folder will be returned.

<added>12345</added>

Adding Contexts

Add a context using the "addContext" API call. The title field is required.

http://api.toodledo.com/api.php?method=addContext;key=YourKey;title=MyContext

If the add was successful the id number of the new context will be returned.

<added>12345</added>

Adding Goals

Add a goal using the "addGoal" API call. The title field is required, and the level and contributes fields are optional.

http://api.toodledo.com/api.php?method=addGoal;key=YourKey;title=MyGoal;level=1;
contributes=12345

If the add was successful the id number of the new goal will be returned.

<added>12345</added>

Editing Tasks

Edit a task using the "editTask" API call. The task id is required and can be found from the getTasks or addTask API calls. Omit any fields that you do not wish to set. 

http://api.toodledo.com/api.php?method=editTask;key=YourKey;
id=12345;title=MyTask;completed=1;folder=123

If the edit was successful you will get the following message.

<success>1</success>

Editing Folders

Edit a folder using the "editFolder" API call. The folder id is required and can be found from the getFolders or addFolder API calls. Omit any fields that you do not wish to set.

http://api.toodledo.com/api.php?method=editFolder;key=YourKey;id=12345;title=MyFolder

If the edit was successful you will get the following message.

<success>1</success>

Editing Contexts

Edit a context using the "editContext" API call. The context id is required and can be found from the getContexts or addContext API calls.

http://api.toodledo.com/api.php?method=editContext;key=YourKey;id=12345;title=MyContext

If the edit was successful you will get the following message.

<success>1</success>

Editing Goals

Edit a goal using the "editGoal" API call. The goal id is required and can be found from the getGoals or addGoal API calls. Omit any fields that you do not wish to set.

http://api.toodledo.com/api.php?method=editGoal;key=YourKey;id=12345;title=MyGoal

If the edit was successful you will get the following message.

<success>1</success>

Deleting Tasks

The "deleteTask" API call will allow you to permanently delete a task. For tasks that you want available in the history section, or for tasks that you want to continue to repeat, you should not use this method. Instead, you should edit the task and mark it as completed.

http://api.toodledo.com/api.php?method=deleteTask;key=YourKey;id=12345;

If the delete was successful you will get the following message.

<success>1</success>

Get Deleted Tasks

The "getDeleted" API call will enable you to detect when a task was deleted on Toodledo, so you can also delete the task from your application.

http://api.toodledo.com/api.php?method=getDeleted;key=YourKey;after=2008-01-25 05:12:45

This returns a list of id numbers and datetime stamps.

<deleted>
	<task>
	<id>12345</id>
	<stamp>2008-02-25 07:46:42</stamp>
	</task>
	<task>
	<id>67890</id>
	<stamp>2008-03-12 14:11:12</stamp>
	</task>
</deleted>

Deleting Folders

The "deleteFolder" API call will allow you to permanently delete a folder. Any tasks that are inside this folder will become folder-less.

http://api.toodledo.com/api.php?method=deleteFolder;key=YourKey;id=12345;

If the delete was successful you will get the following message.

<success>1</success>

Deleting Contexts

The "deleteContext" API call will allow you to permanently delete a context. Any tasks that have this context will have their context set to "none".

http://api.toodledo.com/api.php?method=deleteContext;key=YourKey;id=12345;

If the delete was successful you will get the following message.

<success>1</success>

Deleting Goals

The "deleteGoal" API call will allow you to permanently delete a goal. Any tasks that have this goal will have their goal set to "none".

http://api.toodledo.com/api.php?method=deleteGoal;key=YourKey;id=12345;

If the delete was successful you will get the following message.

<success>1</success>

Retrieving a Userid

The "getUserid" API call will allow you to lookup someone's unique userid from their email login and password.

http://api.toodledo.com/api.php?method=getUserid;email=me@example.com;pass=123456

If the lookup was successful the id number of the person will be returned.

<userid>123456abcdef</userid>

If the userid comes back as 0, it means that either the email or password that you sent was blank. If the userid comes back as 1, it means that the lookup failed. A valid userid will always be a 15 or 16 character hexadecimal string.


Retrieving Account Info

The "getAccountInfo" API call will return some information about the account that you have authenticated.

http://api.toodledo.com/api.php?method=getAccountInfo;key=YourKey

If the lookup was successful, the account info will be returned.

<account>
<userid>123456abcdef</userid>
<alias>Homer</alias>
<pro>1</pro>
<dateformat>0</dateformat>
<timezone>-4</timezone>
<hidemonths>2</hidemonths>
<hotlistpriority>3</hotlistpriority>
<hotlistduedate>5</hotlistduedate>
<lastaddedit>2008-01-24 12:26:45</lastaddedit>
<lastdelete>2008-01-23 15:45:55</lastdelete>
<lastfolderedit>2008-01-23 15:45:55</lastfolderedit>
<lastcontextedit>2008-01-23 15:45:55</lastcontextedit>
<lastgoaledit>2008-01-23 15:45:55</lastgoaledit>
</account>

The values returned have the following definitions:

If you pass "unix=1" along with your API call, the timestamps will be unix timestamps (seconds since 1970) instead of date strings.


Creating an Account

The "createAccount" API call will allow you to create a new account for someone without requiring them to visit our website. When you create an account for someone, you should inform them that they can visit Toodledo.com to customize their account settings.

http://api.toodledo.com/api.php?method=createAccount;email=me@example.com;pass=123456

If the account was created successfully the id number of the person will be returned.

<userid>123456abcdef</userid>

A valid userid will always be a 15 or 16 character hexadecimal string.


Retrieving Server Info

The "getServerInfo" API call will return some information about the server and your current API session.

http://api.toodledo.com/api.php?method=getServerInfo;key=YourKey

If the request was successful, some server info will be returned.

<server>
<unixtime>1204569838</unixtime>
<date>Mon,  3 Mar 2008 12:43:58 -0600</date>
<tokenexpires>45.4</tokenexpires>
</server>

The unixtime and date values represent the current time at the server. This is useful for synchronizing your application's clock with Toodledo's clock, and improves accuracy when comparing modified dates during a synchronization. The tokenexpires value represents the number of minutes left before your token and key expire and when you will need to get a new token.





Home | Help | About | Learning Center | Forums | Contact Us | News | Privacy | Terms | Developer's API | Copyright © 2009