Developer's API Documentation : Tasks

Overview

Tasks allow users to keep track of the things that they need to do. This helps them stay organized and be more productive.

Jump To:

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.
  • tag : A comma separated string listing the tags assigned to this task. Up to 250 characters.
  • 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. 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 make a task no longer repeat, set this field to an empty string.

    This string is in the standard iCal RRULE format. For example: "FREQ=DAILY" or "FREQ=WEEKLY;BYDAY=TU". Not every valid iCal RRULE is understood by Toodledo, but we will be improving our ability to understand more options in the future. Please read our repeat format FAQ for details about how we can currently repeat tasks. Note that users enter their repeat settings using a GUI or by typing a human readable string. These get converted to iCal rules behind the scenes.

    There are three enhancements to the iCal RRULE format that we have made to support some advanced Toodledo features.
    • Subtasks can repeat based on their parent's repeat value. There is not a comparable iCal RRULE for this, so we have a custom RRULE of "PARENT" to indicate this setting.
    • Tasks can be set to repeat from their due-date or their completion date. There is not a way to indicate this in a standard iCAL RRULE. To indicate this, we have a custom string of ";FROMCOMP" that we append to the RRULE if the task is set to repeat from the completion date. The absence of this string means that the task repeats from the due-date.
    • Normally, when a task is rescheduled it moves forwards by 1 occurrence. If the user has procrastinated, the new due-date could still be in the past. Toodledo will have the option to indicate that certain repeating tasks should be rescheduled to the next future occurance of the task. If this is the case, the custom ";FASTFORWARD" string will be appended to the RRULE.
  • 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. New lines should be sent as \n.
  • meta : A text string up to 1024 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.
  • 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).
  • via : A read-only field that indicates how the task was added. These are the possible values:
    • 0: Main website
    • 1: Email Import
    • 2: Firefox Addon
    • 3: This API
    • 4: Widgets (Google Gadget, etc)
    • 5: Not used
    • 6: Mobile Phone
    • 7: iPhone App
    • 8: Import Tools
    • 9: Twitter
  • attachment : An array of attachment items. Each item will contain the following three fields. Attachments are currently read only. You can use the id number to reference the outline, list or note that you can get via this API. File's are not currently readable, but we plan to add this functionality soon.
    • id: The unique id number for the attachment
    • kind: The kind of attachment (file,note,outline,list)
    • name: The display name of the attachment

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 "after" field in this call to request only those tasks that have changed since your last sync.

  • before : A GMT unix timestamp. Used to find tasks with a modified date and time before this date and time.
  • after : 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 and max 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, via, attachments

http://api.toodledo.com/3/tasks/get.php?access_token=yourtoken&after=1234567890&
fields=folder,star,priority

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

[{"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/3/tasks/get.php?access_token=yourtoken&after=1234567890&
fields=folder,star,priority&f=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-10-30</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 with an array of tasks. For each task 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, 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/3/tasks/add.php
	access_token=yourtoken
	tasks=[{"title":"My Task"},{"title":"Another","star":"1","ref":"98765"},{"title":"","ref":"1234"}]
	fields=folder,star

curl --data "access_token=yourtoken&tasks=%5B%7B%22title%22%3A%22My+Task%22%7D%2C%7B%22title%22%3A%22Another%22%2C
%22star%22%3A%221%22%2C%22ref%22%3A%2298765%22%7D%2C%7B%22title%22%3A%22%22%2C%22ref%22%3A%221234%22%7D%5D" 
http://api.toodledo.com/3/tasks/add.php

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.

[{"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"},
{"errorCode":601,"errorDesc":"Your task must have a title","ref":"1234"}]

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

http://api.toodledo.com/3/tasks/add.php
	access_token=yourtoken
	tasks=[{"title"%3A"My Task"}%2C{"title"%3A"Another"%2C"star"%3A"1"%2C"ref"%3A"98765"}%2C{"title"%3A""%2C"ref"%3A"1234"}]
	fields=folder,star
	f=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>
	<error id="601" ref="1234">Your task must have a title</error>
</tasks>

Editing Tasks

You can edit up to 50 tasks at a time by making a POST to the "tasks/edit.php" API call. For each task, 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, 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 handling any subtasks that the task 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 +). Please represent newline characters as \n. 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/3/tasks/edit.php
	access_token=yourtoken
	tasks=[{"id"%3A"1234"%2C"title"%3A"My Task"}%2C{"id"%3A"1235"%2C"title"%3A"Another Task"%2C"star"%3A"1"}
%2C{"id"%3A"5678"%2C"title"%3A"Invalid"}]
	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.

[{"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},
{"errorCode":605,"errorDesc":"Invalid task ID","ref":"5678"}]

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

http://api.toodledo.com/3/tasks/edit.php
	access_token=yourtoken
	tasks=[{"id"%3A"1234"%2C"title"%3A"My Task"}%2C{"id"%3A"1235"%2C"title"%3A"Another Task"%2C"priority"%3A"2"}
%2C{"id"%3A"5678"%2C"title"%3A"Invalid"}]
	fields=folder,star&f=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>
	<error id="605" ref="5678">Invalid task ID</error>
</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 POST. For tasks that the user wants available in the history section, or for tasks that 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/3/tasks/delete.php
	access_token=yourtoken
	tasks=["1234"%2C"1235"%2C"5678"]

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.

[{"id":1234},{"id":1235},{"errorCode":605,"errorDesc":"Invalid ID number","ref":"5678"}]

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

http://api.toodledo.com/3/tasks/delete.php
	access_token=yourtoken
	tasks=["1234"%2C"1235"%2C"5678"]
	f=xml


<deleted>
	<id>1234</id>
	<id>1235</id>
	Invalid ID number
</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/3/tasks/deleted.php&access_token=yourtoken&after=1234567890

This returns a list of id numbers and datetime stamps.

[{"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/3/tasks/deleted.php?access_token=yourtoken&after=1234567890&f=xml

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

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 tasks API endpoints. If there was an error when editing or deleting a task, the id number that you attempted to edit will be included in the error's "ref" field for your reference.

  • 601 : Your task must have a title.
  • 602 : Only 50 tasks can be added/edited/deleted at a time.
  • 603 : The maximum number of tasks allowed per account (80000) has been reached
  • 604 : Empty id
  • 605 : Invalid task
  • 606 : Nothing was added/edited. You'll get this error if you attempt to edit a task but don't pass any parameters to edit.
  • 607 : Invalid folder id
  • 608 : Invalid context id
  • 609 : Invalid goal id
  • 610 : Invalid location id
  • 611 : Malformed request
  • 612 : Invalid parent id
  • 613 : Incorrect field parameters
  • 614 : Parent was deleted
  • 615 : Invalid collaborator
  • 616 : Unable to reassign or share task


Examples: 
JSON:
{"errorCode":601,"errorDesc":"Your task must have a name","ref":1234}


XML:
<error id="601" ref="1234">Your task must have a name</error>