Toodledo
 An easy to use, web-based 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. Here are some things that have been made using our API:

Firefox Add-on - Made by Toodledo

Windows Vista Gadget - Made by Chris Motch

Ruby API/Client - Made by Will Sargent

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. The server responds with an XML document containing the information that you requested.


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:

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

In return you will get a token.

<token>td12345678901234</token>

This token is good for 1 hour. At the end of one hour, you will need to get a new token. 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. If your password, token and myuserid were all "test", your key would be md5(md5("test")+"testtest")=317a1aae7a6cc76e2510c8ade6e6ed05


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 compared 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.


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://www.toodledo.com/api.php?method=getTasks;key=YourKey;shorter=130;
longer=10;priority=2

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

<tasks>
	<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>
		<duedate modifier=""></duedate>
		<duetime>2:00pm</duetime>
		<completed></completed>
		<repeat>1</repeat>
		<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>
		<duedate modifier="=">2008-05-13</duedate>
		<duetime>9:45am</duetime>
		<completed>2008-05-13</completed>
		<repeat>0</repeat>
		<priority>2</priority>
		<length>120</length>
		<timer onfor="123">600</timer>
		<note>Use the car jack</note>
	</task>
</tasks>

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.

http://www.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">Shopping</folder>
	<folder id="456" private="0" archived="0">Home Repairs</folder>
	<folder id="789" private="0" archived="0">Vacation Planning</folder>
	<folder id="234" private="0" archived="0">Chores</folder>
	<folder id="567" private="1" archived="0">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://www.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://www.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">Get a Raise</goal>
	<goal id="456" level="0" contributes="0">Lose Weight</goal>
	<goal id="789" level="1" contributes="456">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://www.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://www.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://www.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://www.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. Please note that repeating tasks that are marked as completed via this API will not be automatically rescheduled. It is your responsibility to reschedule repeating tasks if you use the API.

http://www.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://www.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>

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://www.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://www.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://www.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://www.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://www.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://www.toodledo.com/api.php?method=getUserid;email=me@example.com;pass=12345

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://www.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>
</account>

The values returned have the following definitions:


Retrieving Server Info

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

http://www.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 © 2008