
| 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.
- 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 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.
- title : A text string up to 255 characters. Boolean operators do not work yet, so your search will be for a single phrase. Please encode the & character as %26 and the ; character as %3B.
- tag : A text string up to 64 characters. Please encode the & character as %26 and the ; character as %3B.
- folder : The id number of the folder as returned from the "getFolders" API call. 0 is a special number that returns tasks without a set folder.
- context : The id number of the context as returned from the "getContexts" API call. 0 is a special number that returns tasks without a set context.
- goal : The id number of the goal as returned from the "getGoals" API call. 0 is a special number that returns tasks without a set goal.
- priority : An integer that represents the priority.
- -1 = Negative
- 0 = Low
- 1 = Medium
- 2 = High
- 3 = Top
- repeat : An integer that represents how the tasks repeats.
- 0 = No Repeat
- 1 = Weekly
- 2 = Monthly
- 3 = Yearly
- 4 = Daily
- 5 = Biweekly
- 6 = Bimonthly
- 7 = Semiannually
- 8 = Quarterly
- 9 = With Parent
- parent : This is used to Pro accounts that have access to subtasks. Set this to the id number of the parent task and you will get its subtasks. The default is 0, which is a special number that returns tasks that do not have a parent.
- shorter : An integer representing minutes. This is used for finding tasks with a duration that is shorter than the specified number of minutes.
- longer : An integer representing minutes. This is used for finding tasks with a duration that is longer than the specified number of minutes.
- before : A date formated as YYYY-MM-DD. Used to find tasks with due-dates before this date.
- after : A date formated as YYYY-MM-DD. Used to find tasks with due-dates after this date.
- modbefore : A date-time formated as YYYY-MM-DD HH:MM:SS. Used to find tasks with a modified date and time before this date and time.
- modafter : A date-time formated as YYYY-MM-DD HH:MM:SS. Used to find tasks with a modified date and time after this date and time.
- compbefore : A date formated as YYYY-MM-DD. Used to find tasks with a completed date before this date.
- compafter : A date formated as YYYY-MM-DD. Used to find tasks with a completed date after this date.
- notcomp : Set to 1 to omit completed tasks. Omit variable, or set to 0 to retrieve both completed and uncompleted tasks.
- id : The id number of the task that you want to fetch. This is useful if you already know the id number and only need to fetch the one task.
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.
- title : A text string up to 255 characters. Please encode the & character as %26 and the ; character as %3B.
- tag : A text string up to 64 characters. Please encode the & character as %26 and the ; character as %3B.
- folder : The id number of the folder as returned from the "getFolders" API call. Omit this field or set it to 0 to leave the task unassigned to a folder.
- context : The id number of the context as returned from the "getContexts" API call. Omit this field or set it to 0 to leave the task unassigned to a context.
- goal : The id number of the goal as returned from the "getGoals" API call. Omit this field or set it to 0 to leave the task unassigned to a goal.
- parent : This is used to Pro accounts that have access to subtasks. To create a subtask, set this to the id number of the parent task. The default is 0, which creates a normal task.
- duedate : A date formated as YYYY-MM-DD with an optional modifier attached to the front. Examples: "2007-01-23" , "=2007-01-23" , ">2007-01-23".
- duetime : A date formated as HH:MM MM. Examples: 12:34 am, 4:56 pm.
- repeat : An integer that represents how the tasks will repeat.
- 0 = No Repeat
- 1 = Weekly
- 2 = Monthly
- 3 = Yearly
- 4 = Daily
- 5 = Biweekly
- 6 = Bimonthly
- 7 = Semiannually
- 8 = Quarterly
- 9 = With Parent
- length : An integer representing the number of minutes that the task will take to complete.
- priority : An integer that represents the priority.
- -1 = Negative
- 0 = Low
- 1 = Medium
- 2 = High
- 3 = Top
- note : A text string. Please encode the & character as %26 and the ; character as %3B.
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.
- 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://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.
- title : A text string up to 32 characters.
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.
- 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://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.
- id : The id number of the task to edit.
- title : A text string up to 255 characters representing the name of the task. Please encode the & character as %26 and the ; character as %3B.
- tag : A text string up to 64 characters. Please encode the & character as %26 and the ; character as %3B.
- folder : The id number of the folder (as returned from addFolder or getFolders). A value of 0 will set the task to "No Folder".
- context : The id number of the context (as returned from getContexts). A value of 0 will set the task to "No Context".
- goal : The id number of the goal (as returned from getGoals). A value of 0 will set the task to "No Goal".
- timer : Set to 1 or 0 to turn the timer on or off.
- parent : This is used to Pro accounts that have access to subtasks. To create a subtask, set this to the id number of the parent task. Set it to 0 to turn a subtask back into a task.
- completed : A boolean value (0 or 1) that describes if this task is completed or not.
- duedate : A date formated as YYYY-MM-DD with an optional modifier attached to the front. Examples: "2007-01-23" , "=2007-01-23" , ">2007-01-23". To unset the date, set it to '0000-00-00'.
- duetime : A date formated as HH:MM MM. Examples: 12:34 am, 4:56 pm. To unset the value, set it to 0.
- repeat : An integer that represents how the tasks will repeat.
- 0 = No Repeat
- 1 = Weekly
- 2 = Monthly
- 3 = Yearly
- 4 = Daily
- 5 = Biweekly
- 6 = Bimonthly
- 7 = Semiannually
- 8 = Quarterly
- 9 = With Parent
- length : An integer representing the number of minutes that the task will take to complete.
- priority : An integer that represents the priority.
- -1 = Negative
- 0 = Low
- 1 = Medium
- 2 = High
- 3 = Top
- note : A text string. Please encode the & character as %26 and the ; character as %3B.
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.
- 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://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.
- id : The id number of the task to delete.
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.
- after : A date-time formated as YYYY-MM-DD HH:MM:SS. Used to find tasks that were deleted after this date and time.
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.
- id : The id number of the folder to delete.
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".
- id : The id number of the context to delete.
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".
- id : The id number of the goal to delete.
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.
- email : A text string up to 255 characters.
- pass : A text string up to 255 characters.
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:
- pro : Whether or not the user is a Pro member. 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.
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.