This API is depreciated. Please upgrade to our new improved 3.0 API. This API will continue to work for some time, but it is no longer supported and it will eventually go away.

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.

The API documentation is split between these three pages:

Authentication and General API Tasks API Notebook API

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 should pass an application identifier. This will allow us to track the popularity of different applications and help us monitor and improve our API. This is currently optional, but it will be a requirement in the near future. Apps that do not use an AppID will have tighter rate limitations when using the 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.

Task added in your application
Task edited in your application
Task deleted in your application
Task added on Toodledo
Task edited on Toodledo
Task deleted on Toodledo
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.

Apps that use an AppID (described above), will have more lenient rate limiting.

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>

To fetch a goal's notes, use the "getGoalNotes" API call.

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

This call will return something that looks like this.

<goalNotes>
	<goal id="123">This is my note</goal>
	<goal id="456"></goal>
	<goal id="789">This goal is important.</goal>
</goalNotes>

Adding Folders

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

title : A text string up to 32 characters.
private : A boolean value (0 or 1) that describes if this folder can be shared. A value of 1 means that this folder is private.

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.

title : A text string up to 32 characters.

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.

title : A text string up to 255 characters.
level : The integer 0, 1 or 2 specifying the level. The default is 0. (0=lifetime, 1=long-term, 2=short-term)
contributes : The id number returned from the "getGoals" API call for the higher level goal that this goal contributes to.

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

id : The id number of the folder to edit.
title : A text string up to 32 characters.
private : A boolean value (0 or 1) that describes if this folder can be shared. A value of 1 means that this folder is private.
archived : A boolean value (0 or 1) that describes if this folder is archived.

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.

id : The id number of the context to edit.
title : A text string up to 32 characters.

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.

id : The id number of the goal to edit.
title : A text string up to 255 characters.
level : The integer 0, 1 or 2 specifying the level. The default is 0. (0=lifetime, 1=long-term, 2=short-term)
contributes : The id number returned from the "getGoals" API call for the higher level goal that this goal contributes to.
archived : A boolean value (0 or 1) that describes if this goal is archived.

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 Folders

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

id : The id number of the folder to delete.

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

id : The id number of the context to delete.

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

id : The id number of the goal to delete.

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.

email : A text string up to 255 characters.
pass : A text string between 6 and 255 characters.

http://api.toodledo.com/api.php?method=getUserid;[email protected];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 alphanumeric 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:

pro : Whether or not the user is a Subscriber. You need to know this if you want to use subtasks.
dateformat : The user's prefered format for representing dates. (0=M D, Y, 1=M/D/Y, 2=D/M/Y, 3=Y-M-D)
timezone : The number of half hours that the user's timezone is offset from the server's timezone. A value of -4 means that the user's timezone is 2 hours earlier than the server's timezone.
hidemonths : If the task is due this many months into the future, the user wants them to be hidden.
hotlistpriority : The priority value above which tasks should appear on the hotlist.
hotlistduedate : The due date lead-time by which tasks should will appear on the hotlist.
lastaddedit : A timestamp that indicates the last time that any task was added or edited on this account. You can quickly check this field to determine if you need to download updates.
lastdelete : A timestamp that indicates the last time that any task was deleted from this account. You can quickly check this field to determine if you need to identify and remove tasks from your application.
lastfolderedit : A timestamp that indicates the last time that a folder was added, edited or deleted. You can quickly check this field to determine if you need to call getFolders to refresh your cached folder list.
lastcontextedit : A timestamp that indicates the last time that a context was added, edited or deleted. You can quickly check this field to determine if you need to call getContexts to refresh your cached context list.
lastgoaledit : A timestamp that indicates the last time that a goal was added, edited or deleted. You can quickly check this field to determine if you need to call getGoals to refresh your cached goal list.

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.

email : A valid email address.
pass : A text string betweeen 6 and 255 characters.

http://api.toodledo.com/api.php?method=createAccount;[email protected];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 alphanumeric 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>
<serveroffset>18000</serveroffset>
<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.