Developer's API Documentation : Folders

Overview

Folders are a way to organize tasks and notes into groups. Most people use folders to keep different projects or areas of their life separated.

Jump To:

Syncing

Syncing folders is fairly straight forward. The first thing to do is add any new folders you have created and delete any folders that you have deleted. Then, look at the "lastedit_folder" timestamp returned from Account Info to determine if any changes have happened on the server since the last time you synced. If yes, then you need to fetch the folders from the server and integrate this into your local copy. This is where you would do conflict resolution if a folder was edited in both places. After this, if you have any folders that you edited, you can send these edits up to the server.

Sync Flowchart

Retrieving Folders

The "folders/get.php" API call will return a list of your folders. You can access this via GET or POST. The 'private' boolean value indicates that the user does not want the folder to be shared with other people. The 'archived' boolean value indicates that the user no longer wants to see this folder, but wants to retain it for historical purposes. The 'order' integer represents the user's preferred order for listing folders with ord=1 being the top.

http://api.toodledo.com/3/folders/get.php?access_token=yourtoken

This call will return a JSON encoded object that looks like this.

[{"id":123,"name":"Shopping","private":0,"archived":0,"ord":1},
{"id":456,"name":"Home Repairs","private":0,"archived":0,"ord":2},
{"id":789,"name":"Vacation PLanning","private":0,"archived":0,"ord":3}]

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/folders/get.php?access_token=yourtoken&f=xml


<folders>
	<folder><id>123</id><private>0</private><archived>0</archived>
	<order>1</order><name>Shopping</name></folder>
	<folder><id>456</id><private>0</private><archived>0</archived>
	<order>2</order><name>Home Repairs</name></folder>
	<folder><id>789</id><private>1</private><archived>0</archived>
	<order>3</order><name>Vacation Planning</name></folder>
</folders>

Adding Folders

Add a folder using the "folders/add.php" API call. You can access this via POST. Folder names must be unique within an account. If you try to add a folder that already exists, you'll get an error. Each user can have up to 1000 folders. If you try to add more than this, you will get an error.

  • name : A text string up to 64 characters. (required)
  • 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/3/folders/add.php
	name=MyFolder
	access_token=yourtoken

If the add was successful the new folder will be returned.

 
[{"id":12345,"name":"MyFolder","private":0,"archived":0,"ord":1}]


<folders>
	<folder><id>12345</id><private>0</private><archived>0</archived>
	<order>1</order><name>MyFolder</name></folder>
</folders>

Editing Folders

Edit a folder using the "folders/edit.php" API call. You can access this via POST. Folder names must be unique within an account. If you try to edit the folder name to one that already exists, you will get an error. If you try to edit the folder, but pass in the same values that already exist on the server, you will get an error. You should avoid making unnecessary edits.

  • id : The id number of the folder to edit. (required)
  • name : A text string up to 64 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/3/folders/edit.php
	id=12345
	name=MyFolder
	private=0
	access_token=yourtoken

If the edit was successful the edited folder will be returned.

[{"id":12345,"name":"MyFolder","private":0,"archived":0,"ord":1}]


<folders>
	<folder><id>12345</id><private>0</private><archived>0</archived>
	<order>1</order><name>MyFolder</name></folder>
</folders>

Deleting Folders

The "folders/delete.php" API call will allow you to permanently delete a folder. You can access this via POST. Any tasks or notes that currently have this folder will have their folder set to 0 (none).

  • id : The id number of the folder to delete. (required)

http://api.toodledo.com/3/folders/delete.php
	id=12345
	access_token=yourtoken

If the delete was successful you will get the following message.

{"deleted":12345}


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

  • 201 : Your folder must have a name.
  • 202 : A folder with that name already exists.
  • 203 : Max folders reached (1000).
  • 204 : Empty id.
  • 205 : Invalid folder.
  • 206 : Nothing was edited.


Examples: 
JSON:
{"errorCode":202,"errorDesc":"A folder with that name already exists","ref":1234}


XML:
<error id="202" ref="1234">A folder with that name already exists</error>