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.

  • id : The server id number for this list. This will be a hexadecimal string of 24-36 characters.
  • title : A string for the name of the list. Up to 100 characters.
  • keywords : A comma separated string of keywords or tags, up to 200 characters. Keywords are used to organize, sort and search for lists.
  • note : A string for a longer note about this list. Up to 2000 characters.
  • modified : A GMT unix timestamp for when the list was last modified.
  • added : A GMT unix timestamp for when the list was added.
  • cols : An array of column definitions. Each column definition will contain the following fields:
    • id : The id number for this column. The API will create these for you.
    • title : The title of this column as entered by user.
    • type : An integer presenting the column type.
      • 1 = Checkbox
      • 2 = Currency
      • 3 = Date
      • 4 = Date + Time
      • 5 = Email Address
      • 6 = Icon
      • 8 = Duration
      • 9 = List (pick multiple)
      • 10 = List (pick one)
      • 12.1 = Number (1 decimal place)
      • 12.2 = Number (2 decimal places)
      • 12.3 = Number (3 decimal places)
      • 12.4 = Number (4 decimal places)
      • 13 = Number (integer)
      • 14 = Percent
      • 15 = Phone Number
      • 16 = Rating
      • 17 = Star
      • 18 = Text (Long)
      • 19 = Text (Short)
      • 21 = URL
      • 22 = Year
    • width : The width in pixels of the column. The minimum value is 50.
    • sort : Indicates if the user has sorted by this column. 0 means that the list is not sorted by this column. 1 means that it is the primary sort. -1 means that it is the primary sort, but in reverse order. 2/-2 are use for secondary sort and 3/-3 are used for tertiary sort.
  • version : An integer indicating which version or revision this list is on. Each time it is edited, this number will increment by one. It is used for conflict resolution when editing lists simultaneously on two separate clients.
  • ref : This field is only used for adding a list to ensure that the same list is not added twice. Set this to a reference to your local copy's id number or create a unique identifier for it.
  • rows : A read-only integer that indicates the number of rows in the list.

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.

  • before : A GMT unix timestamp. Used to find lists with a modified date and time before this date and time.
  • after : A GMT unix timestamp. Used to find lists with a modified date and time after this date and time.
  • id : The id number of the lists that you want to fetch. This is useful if you already know the id number and only need to fetch the one lists.
  • 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.

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.

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

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.

  • 901 : List had no title
  • 902 : Only 50 lists can be added/edited/deleted at a time.
  • 903 : Max lists reached
  • 904 : Empty id
  • 905 : Invalid list
  • 906 : Nothing was added/edited
  • 907 : Invalid list id
  • 909 : List already added
  • 911 : Malformed request
  • 912 : Reference was empty
  • 913 : Invalid cols format
  • 914 : Editing wrong version


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>