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.

  • id : The server id number for this task. It is guaranteed to be unique per account, but two different accounts may have two different tasks with the same id number.
  • title : A string for the name of the task. Up to 255 characters. When setting, please encode the & character as %26 and the ; character as %3B.
  • tag : A comma separated string listing the tags assigned to this task. Up to 64 characters. When setting, please encode the & character as %26 and the ; character as %3B.
  • folder : The id number of the folder. Omit this field or set it to 0 to leave the task unassigned to a folder.
  • context : The id number of the context. Omit this field or set it to 0 to leave the task unassigned to a context.
  • goal : The id number of the goal. Omit this field or set it to 0 to leave the task unassigned to a goal.
  • location : The id number of the location. Omit this field or set it to 0 to leave the task unassigned to a location.
  • parent : This is used with Subscriptions 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.
  • children : This is used with Subscriptions that have access to subtasks. This will indicate the number of child tasks that this task has. This will be 0 for subtasks or for regular tasks without subtasks.
  • order : This is used with Subscriptions that have access to subtasks. This is an integer that indicates the manual order of subtasks within the parent task. Currently this is read-only.
  • duedate : A GMT unix timestamp for when the task is due. The time component of this timestamp doesn't matter. When fetching from the server, it will always be noon.
  • duedatemod : An integer representing the due date modifier.
    • 0 = Due By
    • 1 = Due On (=)
    • 2 = Due After (>)
    • 3 = Optionally (?)
  • startdate : A GMT unix timestamp for when the task starts. The time component of this timestamp will always be noon.
  • duetime : A GMT unix timestamp for when the task is due. If the task does not have a time set, then this will be 0. If the task has a duetime without a duedate set, then the date component of this timestamp will be Jan 1, 1970. Times are stored as floating times. In other words, 10am is always 10am, regardless of your timezone. You can convert this timestamp to a GMT string and display the time component without worrying about timezones.
  • starttime : A GMT unix timestamp for when the task starts. If the task does not have a time set, then this will be 0. If the task has a starttime without a startdate set, then the date component of this timestamp will be Jan 1, 1970. Times are stored as floating times. In other words, 10am is always 10am, regardless of your timezone. You can convert this timestamp to a GMT string and display the time component without worrying about timezones.
  • remind : An integer that represents the number of minutes prior to the duedate/time that a reminder will be sent. Set it to 0 for no reminder. Values will be constrained to this list of valid numbers (0, 1, 15, 30, 45, 60, 90, 120, 180, 240, 1440, 2880, 4320, 5760, 7200, 8640, 10080, 20160, 43200). Additionally, if the user does not have a Subscription, the only valid numbers are 0,60. If you submit an invalid number, it will be rounded up or down to a valid non zero value.
  • repeat : A string indicating how the task repeats. For example: "Every 1 Week" or "On the 2nd Friday". Please read our repeat format faq for details about valid values. When a task is rescheduled, it is moved forward to the new date. For record keeping purposes, a completed copy of this task will be added to the user's list. It will have a new ID number and will be already completed. To unset this value, set it to an empty string.
  • repeatfrom : Indicates how tasks repeat. It will be 0 to repeat from the due-date or 1 to repeat from the completion date. If you are changing this value, you must also send the "repeat" field when making an API call.
  • status : An integer that represents the status of the task.
    • 0 = None
    • 1 = Next Action
    • 2 = Active
    • 3 = Planning
    • 4 = Delegated
    • 5 = Waiting
    • 6 = Hold
    • 7 = Postponed
    • 8 = Someday
    • 9 = Canceled
    • 10 = Reference
  • 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
  • star : A boolean (0 or 1) that indicates if the task has a star or not.
  • modified : A GMT unix timestamp for when the task was last modified.
  • completed : A GMT unix timestamp for when the task was completed. If the task is not completed, the value will be 0. Toodledo does not track the time that a task was completed, so tasks will always appear to be completed at noon.
  • added : A GMT unix timestamp for when the task was added. Toodledo does not track the time that a task was added, so tasks will always appear to be added at noon.
  • timer : The value in the timer field indicates the number of seconds that have elapsed for the timer not including the current session.
  • timeron : If the timer is currently on, this 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-timeron). Where "now" is a unix timestamp for the current time.
  • note : A text string up to 32,000 bytes long. When setting, please encode the & character as %26 and the ; character as %3B.
  • meta : A text string up to 255 bytes long for storing metadata about the task. This is useful for syncing data that cannot otherwise be synced to Toodledo. This data is unique per task ID. This data is private to your App ID. Neither the user, nor other App IDs can see the data that you put in here. Because of an implementation detail, using the meta field introduces extra latency to each API call, so you should only use this field when necessary.
  • previous : If the task was repeated from another task, this will contain the id number of the previous version of this task.
  • attachment : A boolean (0 or 1) that indicates if the task has an attachment or not (Subscription required for user).
  • shared : A boolean (0 or 1) that indicates if the task is shared as a joint task (Subscription required for user). Read only.
  • sharedowner : The user id of the person who owns the task that is being shared with the current user. If the current user is not the owner, then they cannot make changes to the collaboration settings for this task, although they can make other changes. Read only.
  • sharedwith : An array of user ids for people that this task is shared with, other than myself and the owner. Read only.
  • addedby : The user id of the collaborator who assigned the task (Subscription required for user).

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.

  • modbefore : A GMT unix timestamp. Used to find tasks with a modified date and time before this date and time.
  • modafter : A GMT unix timestamp. Used to find tasks with a modified date and time after this date and time.
  • comp : Boolean (0 or 1). Set to 0 to find only uncompleted tasks. Set to 1 to find only completed tasks. Omit variable, or set to -1 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.
  • start : The number of records that you want to skip before printing results. Use this in combination with "num" if you want to paginate your results. The default value is 0.
  • num : The number of records to go through until output is stopped. Use this in combination with "start" if you want to paginate your results. The default value is 1000.
  • fields : A comma separated list of optional fields that you want returned. For efficiency, you should omit fields that you don't use. This will make downloading, parsing and syncing go much faster.

    Always returned (do not list in the fields paramater or you will get an error):
    id, title, modified, completed

    Optional:
    folder, context, goal, location, tag, startdate, duedate, duedatemod, starttime, duetime, remind, repeat, status, star, priority, length, timer, added, note, parent, children, order, meta, previous, attachment, shared, addedby

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>2024-11-21</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.

  • after : A GMT unix timestamp. Used to find tasks with a deletion date and time after this date and time.

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.

  • id : The id number of the task being reassigned.
  • assign : The user id that it is being reassigned to (found in the account/collaborators.php API call). Before you call this, be sure that the user has permission to be reassigned a task (has a 1 in the reassignable field from account/collaborators.php)

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.

  • id : The id number of the task being shared.
  • share : A comma separated list of user ids to share the task with (found in the account/collaborators.php API call). To unshare a tasks with someone, remove their user id from the list and resubmit this query. To unshare the task with everyone, submit an empty array.

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.

  • 1 : You did not specify a key for authentication.
  • 2 : The authentication key that you provided has expired or is invalid.
  • 3 : Only 50 tasks can be added/edited/deleted at a time.
  • 4 : You didn't specify any tasks to add/edit/delete.
  • 5 : The task's title cannot be blank.
  • 6 : The maximum number of tasks allowed per account (80000) has been reached.
  • 7 : Invalid task ID number.
  • 8 : Invalid folder ID.
  • 9 : Invalid context ID.
  • 10 : Invalid goal ID.
  • 11 : Invalid location ID.
  • 12 : Nothing was changed. You'll get this error if you attempt to edit a task but don't pass any parameters to edit.
  • 13 : Invalid parent ID.
  • 100 : Unknown Error.
  • 500 : The Toodledo server is offline for maintenance.


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


XML:
<error id="5">A goal with that name already exists</error>