Developer's API Documentation : Folders

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 thsi 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/2/folders/get.php?key=YourKey

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

JSON:
[{"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/2/folders/get.php?key=YourKey;f=xml


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 GET or POST. Fonder 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 32 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/2/folders/add.php?name=MyFolder;key=YourKey

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

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


XML: 
<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 GET or 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 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://api.toodledo.com/2/folders/edit.php?id=12345;name=MyFolder;key=YourKey

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

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


XML: 
<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 GET or POST. Any tasks that have this folder will have their folder set to "none".

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

http://api.toodledo.com/2/folders/delete.php?id=12345;key=YourKey

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

JSON: 
{"deleted":"12345"}


XML: 
<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 folders API.

  • 1 : You did not specify a key for authentication.
  • 2 : The authentication key that you provided has expired or is invalid.
  • 3 : No folder was specified. The id number is a required paramater.
  • 4 : The folder specified in your call does not exist.
  • 5 : You tried to add or edit a folder with a name that already exists.
  • 6 : The user has the maximum number of folders (1000), so you can't add any more.
  • 7 : You tried to add or edit a folder without a name. A folder must have a name.
  • 8 : You tried to edit a folder with values that already exist. Nothing was changed. If you get this a lot, you are making unnecessary edits.
  • 100 : Unknown Error.
  • 500 : The Toodledo server is offline for maintenance.


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


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