Developer's API Documentation : Tasks




Syncing

Syncing tasks is the main purpose of most third-party applications. If you use the following recommendations you can sync cleanly and efficiently. One of the most important things is to use the "lastedit_task" and "lastdelete_task" timestamps, returned from Account Info, to determine if any changes have happened on the server before you fetch anything. In the vast majority of cases, when syncing, nothing will have changed on the server and you won't even need to do anything.

Sync Flowchart

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 "/tasks/add.php", "/tasks/edit.php" or "/tasks/delete.php" 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 "/tasks/get.php" and "/tasks/get_deleted.php" 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. See the flowchart for an efficient way to handle all scenarios.





Task Datatypes

There are a number of fields that can be set or retrieved when working with tasks. Here is a description of these fields.





Retrieving Tasks

The "tasks/get.php" API call will return a list of the tasks that match your search parameters. You can access this via GET or POST. The following search parameters may be used to limit the returned tasks. To make sync go as efficiently as possible you should request the minimum amount of data that you need. Usually, this means keeping track of the "lastedit_task" field from the account/get.php API call and using this in combination with the "modafter" field in this call to request only those tasks that have changed since your last sync.


http://api.toodledo.com/2/tasks/get.php?key=YourKey;modafter=1234567890;
fields=folder,star,priority

This returns a list of tasks in the JSON format, like this.

JSON: 
[{"num":"2","total":"2"}, {"id":"1234","title":"Buy Milk","modified":1281990824,
"completed":0,"folder":"5409195","star":"1","priority":"-1"},{"id":"1235",
"title":"Fix flat tire","modified":1280877483,"completed":1280808000,
"folder":"0","star":"0","priority":"0"}]

You can also specify xml as the output format for any API calls by attaching "f=xml" to the URL.

http://api.toodledo.com/2/tasks/get.php?key=YourKey;modafter=1234567890;
fields=folder,star,priority;f=xml

XML: 
<tasks num="2" total="2">
	<task>
		<id>1234</id>
		<title>Buy Milk</title>
		<folder>123</folder>
		<modified>1234567890</modified>
		<completed></completed>
		<star>0</star>
		<priority>2</priority>
	</task>
	<task>
		<id>1235</id>
		<title>Fix flat tire</title>
		<folder>456</folder>
		<modified>1234567890</modified>
		<completed>2014-09-19</completed>
		<star>1</star>
		<priority>2</priority>
	</task>
</tasks>




Adding Tasks

You can add up to 50 tasks at a time by making a POST to the "tasks/add.php" API call. The title field is required, and the following fields are optional: folder, context, goal, location, priority, status,star, duration, remind, starttime, duetime, completed, duedatemod, repeat, repeatFrom, tag, duedate, startdate, note, parent, meta (see above for possible values).

There is also a special field called "ref" that you can use to pass through an alphanumeric id number to aid in matching things up after a sync. The "ref" field is not saved into the task, it is only echoed back to you on this call.

Tasks are added by creating a JSON object (example below) and submitting a POST to the API. Please represent newline characters as \n. Be sure to encode the data properly for transfer via a URL (symbols replaced with their %XX equivalent and spaces encoded as +). Each element in the array will be a task object. You only need to set the fields that you want to set. For efficiency, you should try to send only the fields that you are setting.

http://api.toodledo.com/2/tasks/add.php?key=YourKey;
tasks=[{"title"%3A"My Task"}%2C{"title"%3A"Another"%2C"star"%3A"1"%2C"ref"%3A"98765"}];
fields=folder,star

If the action was successful the added tasks will be returned in the same order in which they were added. If there were any errors on individual tasks, they will be output inline with the returned tasks, so you can determine which action failed.

JSON: 
[{"id":"1234","title":"My Task","modified":1281990824,"completed":0,"folder":"0","star":"0"},
{"id":"1235","title":"Another","modified":1280877483,"completed":0,"folder":"0","star":"1","ref":"98765"}]

You can also specify xml as the output format for any API calls by attaching "f=xml" to the URL.

http://api.toodledo.com/2/tasks/add.php?key=YourKey;
tasks=[{"title"%3A"My Task"}%2C{"title"%3A"Another"%2C"star"%3A"1"%2C"ref"%3A"98765"}];
fields=folder,star;f=xml

XML: 
<tasks>
	<task>
		<id>1234</id>
		<title>My Task</title>
		<folder>0</folder>
		<modified>1234567890</modified>
		<completed></completed>
		<star>0</star>
	</task>
	<task>
		<id>1235</id>
		<title>Another</title>
		<folder>0</folder>
		<modified>1234567890</modified>
		<completed></completed>
		<star>1</star>
		<ref>98765</ref>
	</task>
</tasks>



Editing Tasks

You can edit up to 50 tasks at a time by making a POST to the "tasks/edit.php" API call. The id field is required, and the following fields are optional: title, folder, context, goal, location, priority, status,star, duration, remind, starttime, duetime, completed, duedatemod, repeat, repeatFrom, tag, duedate, startdate, note, parent, meta (see above for possible values).

Additionally, you can set the "reschedule" variable to "1" if you want Toodledo to automatically reschedule the repeating task for you. This will only apply if you also set the completion date, and if the task has a due-date and repeating value. If you do not set this, then you are responsible for rescheduling repeating tasks yourself, as well as properly hyandling any subtasks that the user may have. It is recommended that you allow Toodledo to reschedule repeating tasks for you.

Tasks are added by creating a JSON object (example below) and submitting a POST to the API. Be sure to encode the data properly for transfer via a URL (symbols replaced with their %XX equivalent and spaces encoded as +). Each element in the array will be a task object. You only need to set the fields that you want to set. For efficiency, you should try to send only the fields that have changed.

http://api.toodledo.com/2/tasks/edit.php?key=YourKey;
tasks=[{"id"%3A"1234"%2C"title"%3A"My Task"}%2C{"id"%3A"1235"%2C"title"%3A"Another Task"%2C"star"%3A"1"}];
fields=folder,star

If the action was successful the edit tasks will be returned. If there were any errors on individual tasks, they will be output inline with the returned tasks, so you can determine which action failed.

JSON: 
[{"id":"1234","title":"My Task","modified":1281990824,"completed":0,"folder":"0","star":"0"},
{"id":"1235","title":"Another","modified":1280877483,"completed":0,"folder":"0","star":"1"}]

You can also specify xml as the output format for any API calls.

http://api.toodledo.com/2/tasks/edit.php?key=YourKey;
tasks=[{"id"%3A"1234"%2C"title"%3A"My Task"}%2C{"id"%3A"1235"%2C"title"%3A"Another Task"%2C"priority"%3A"2"}];
fields=folder,star;f=xml

XML: 
<tasks>
	<task>
		<id>1234</id>
		<title>My Task</title>
		<folder>0</folder>
		<modified>1234567890</modified>
		<completed></completed>
		<star>0</star>
	</task>
	<task>
		<id>1235</id>
		<title>Another Task</title>
		<folder>0</folder>
		<modified>1234567890</modified>
		<completed></completed>
		<star>1</star>
	</task>
</tasks>



Deleting Tasks

The "/tasks/delete.php" API call will allow you to permanently delete up to 50 tasks at a time. You can access this via GET or POST. 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.

Tasks are deleted by submitting a JSON encoded array of id numbers to the API.

http://api.toodledo.com/2/tasks/delete.php?key=YourKey;tasks=["1234"%2C"1235"]

If the action was successful the deleted tasks's id numbers will be returned. If there were any errors on individual tasks, they will be output inline with the returned tasks, so you can determine which action failed.

JSON: 
[{"id":"1234"},{"id":"1235"}]

You can also specify xml as the output format for any API calls.

http://api.toodledo.com/2/tasks/delete.php?key=YourKey;tasks=["1234"%2C"1235"];f=xml

XML: 
<deleted>
	<id>1234</id>
	<id>1235</id>
</deleted>



Get Deleted Tasks

The "/tasks/deleted.php" API call will enable you to detect when a task was deleted on Toodledo, so you can also delete the task from your application. You can access this via GET or POST.


http://api.toodledo.com/2/tasks/deleted.php;key=YourKey;after=1234567890

This returns a list of id numbers and datetime stamps.

JSON: 
[{"num":"24"},{"id":"1234","stamp":"1234567891"},{"id":"1235","stamp":"1234567892"}]

You can also specify xml as the output format for any API calls.

http://api.toodledo.com/2/tasks/deleted.php?key=YourKey;after=1234567890;f=xml

XML: 
<deleted num="2">
	<task>
	<id>12345</id>
	<stamp>1234567891</stamp>
	</task>
	<task>
	<id>67890</id>
	<stamp>1234567892</stamp>
	</task>
</deleted>



Reassign a Task

The "/tasks/reassign.php" API call will enable you to reassign a task to a collaborator. You can access this via POST. This function is only available to accounts with a Subscription.


http://api.toodledo.com/2/tasks/reassign.php;key=YourKey;id=1234;assign=td56789abcd

This returns 0 or 1 to indicate failure or success. A reassignment can fail if the user does not have permission to reassign the task, or if the task is already shared jointly. Once the task has been successfully reassigned, it will be deleted from the current user's account and will appear in calls to /tasks/deleted.php.




Share a Task

The "/tasks/share.php" API call will enable you to jointly share a task with any number of collaborators. They can edit the task and the changes will be reflected in everyone's account. You can access this via POST. This function is only available to accounts with a Subscription. Only the owner of a task can make changes to how a task is shared.


http://api.toodledo.com/2/tasks/share.php;key=YourKey;id=1234;share=td56789abcd,td12345xyz

This returns 0 or 1 to indicate failure or success. A share can fail if the user does not have permission to share the task.




Error Codes

Any of the API calls can return error messages. Here is a list of the error messages that you may receive from the goals API.



Examples:
JSON:
{"errorCode":1,"errorDesc":"Empty key"}

XML:
<error id="5">A goal with that name already exists</error>
Toodledo.com | API Home | Forums | Contact Us | Blog | Jobs | Press | Privacy | Terms | Copyright © 2006-2014  3