Developer's API Documentation : Lists


Overview

The Lists section provides a way to make customizable lists for any purpose. You can customize the columns with over 20 different data types and then you can add rows to your list. This page describes how to create, edit and delete lists, which are the containers that hold rows. Once you have a list, you can add rows using our Rows API.

Jump To:





List Datatypes

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





Retrieving Lists

The "lists/get.php" API call will return a list of the lists that match your search parameters. You can access this via GET or POST. The following search parameters may be used to limit the returned lists. To make sync go as efficiently as possible you should request the minimum amount of data that you need. Usually, this means using the "after" field in this call to request only those lists that have changed since your last sync. You should look at the "lastedit_list" timestamp, 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.


http://api.toodledo.com/3/lists/get.php?access_token=yourtoken&after=1234567890

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

[{"id":"52ab6f31f143149217ef5d3a","added":1386966833,"modified":1386966833,"title":"New List",
"cols":[{"title":"Title","type":19,"id":1,"sort":1,"width":100}],"version":10,
"note":"My Note","keywords":"keyword1, keyword2","rows":5}]

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

http://api.toodledo.com/3/lists/get.php?access_token=yourtoken&after=1234567890&f=xml

<lists>
	<list>
		<id>52ab6aa8c725c1ac008b46c4</id>
		<title>My List</title>
		<added>1386965672</added>
		<modified>1386965691</modified>
		<version>10</version>
		<note>A helpful note</note>
		<keywords>keyword1, keyword2</keywords>
		<rows>5</rows>
		<cols>
			<col>
				<id>1</id>
				<title>Title</title>
				<type>19</type>
				<sort>1</sort>
				<width>100</width>
			</col>
		</cols>
	</list>
</lists>




Adding Lists

You can add up to 50 lists at a time by making a POST to the "lists/add.php" API call.

Lists are added by creating a JSON object (example below) and submitting a POST with the field name "lists" 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 list object. You only need to set the fields that you want to set, although "title" and "ref" are required. For efficiency, you should try to send only the fields that you are setting.

A list cannot exist without at least one column. If you omit the "cols" field, a default column will be added for you. When adding a list with columns, the title and type are the only required fields. Leave the "id" field blank as the API will generate the column ids for you. The sort and width fields are optional.

The "ref" field is a special field that you can use to pass through an id number to aid in matching things up after a sync. It is also used to ensure that the same list is not added multiple times, so make sure you send a unique identifier as the "ref" for each new list.

http://api.toodledo.com/3/lists/add.php
	access_token=yourtoken
	lists=[{"title":"New%20List","ref":"123456"}]

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

[{"id":"52ab6f31f143149217ef5d3a","added":1386966833,"modified":1386966833,"title":"New List",
"cols":[{"title":"Title","type":19,"id":1,"sort":1,"width":100}],"version":1,"ref":"123456","note":null,"keywords":null,"rows":0}]

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

http://api.toodledo.com/3/lists/add.php
	access_token=yourtoken
	f=xml
	lists=[{"title":"New%20List","ref":"123456"}]

<lists>
	<list>
		<id>52c5e235f14314a94e7ed13d</id>
		<title>New List</title>
		<added>1388700213</added>
		<modified>1388700213</modified>
		<version>1</version>
		<note></note>
		<keywords></keywords>
		<rows>0</rows>
		<cols>
			<col>
				<id>1</id>
				<title>Title</title>
				<type>19</type>
				<sort>1</sort>
				<width>100</width>
			</col>
		</cols>
	</list>
</lists>




Editing Lists

You can edit up to 50 lists at a time by making a POST to the "lists/edit.php" API call with the "lists" field set to an array of lists to edit. For each list edited, the "id" and "version" field are required, and the following fields are optional: title, keywords, note, cols.

Lists are edited 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 list object.

http://api.toodledo.com/3/lists/edit.php
	access_token=yourtoken
	lists=[{"id":"52ab70f7f143149317ef5d38","title":"Edited%20List","version":"2"}]
	

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

[{"id":"52ab70f7f143149317ef5d38","added":1386967287,"modified":1386967954,"title":"Edited List",
"cols":[{"title":"Title","type":19,"id":1,"sort":1,"width":100}],"version":3,"note":"","keywords":"","rows":5}]

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

http://api.toodledo.com/3/lists/edit.php
	access_token=yourtoken
	f=xml
	lists=[{"id":"52ab70f7f143149317ef5d38","title":"Edited%20List","version":"2"}]

 
<lists>
	<list>
		<id>52c5e235f14314a94e7ed13d</id>
		<title>Edited List</title>
		<added>1388700213</added>
		<modified>1388700213</modified>
		<version>3</version>
		<note></note>
		<keywords></keywords>
		<rows>0</rows>
		<cols>
			<col>
				<id>1</id>
				<title>Title</title>
				<type>19</type>
				<sort>1</sort>
				<width>100</width>
			</col>
		</cols>
	</list>
</lists>




Deleting Lists

The "/lists/delete.php" API call will allow you to permanently delete up to 50 lists at a time. You can access this via POST.

Lists are deleted by submitting a JSON encoded array of ids to the API.

http://api.toodledo.com/3/lists/delete.php
	access_token=yourtoken
	lists=["1234abc"%2C"1235def"]

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

[{"id":"1234abc"},{"errorCode":805,"errorDesc":"Invalid ID number","ref":"1235def"}]

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

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

 
<deleted>
	<id>1234abc</id>
	<error id="805" ref="1235def">Invalid ID number</error>
</deleted>




Get Deleted Lists

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


http://api.toodledo.com/3/lists/deleted.php&access_token=yourtoken&after=1234567890

This returns a list of id numbers and datetime stamps.

[{"id":"5238ca9af14314cf4c4f5fa4","deleted":1386199410},{"id":"52a7706df143142d7aef5d30","deleted":1386705006}]

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

http://api.toodledo.com/3/lists/deleted.php?access_token=yourtoken&after=1234567890&f=xml

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



Examples:
JSON:
{"errorCode":801,"errorDesc":"Your list must have a name","ref":"1234abc"}

XML:
<error id="801" ref="1234abc">Your list must have a name</error>
Toodledo.com | API Home | Forums | Contact Us | Blog | Jobs | Press | Privacy | Terms | Copyright © 2006-2014  4