Developer's API Documentation : Rows

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 rows for a specified list. To create a list, please us our Lists API.

Jump To:

Row Datatypes

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

  • id : The server id number for this row. This will be a hexadecimal string of 24-36 characters.
  • modified : A GMT unix timestamp for when the row was last modified.
  • added : A GMT unix timestamp for when the row was added.
  • version : An integer indicating which version or revision this row is on. Each time it is edited, this number will increment by one. It is used for conflict resolution when editing rows simultaneously on two separate clients.
  • ref : This field is only used for adding a row to ensure that the same row is not added twice. Set this to a reference to your local copy's id number or create a unique identifier for it.
  • cells : An array of cells for this row. Each cell has a key and a value. The key is the letter "c" followed by the id number for the column. You can get the column id from the lists API. The value will be string, number or array value for this column. For example: cells["c1"] = "MyText"; cells["c2"] = 42;

Retrieving Rows

The "rows/get.php" API call will return a list of the rows that match your search parameters. You can access this via GET or POST. The following search parameters may be used to limit the returned rows. 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 rows that have changed since your last sync.

  • list : The id number for the list that you want to fetch rows from (required).
  • before : A GMT unix timestamp. Used to find rows with a modified date and time before this date and time.
  • after : A GMT unix timestamp. Used to find rows with a modified date and time after this date and time.
  • id : The id number of the row that you want to fetch. This is useful if you already know the id number and only need to fetch the one row.
  • 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/rows/get.php?access_token=yourtoken&after=1234567890&list=1234567890

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

[{"id":"52c71040f14314a94e7ed14f","added":1388771536,"modified":1388777536,"version":5,"list":"1234567890","cells":{"c1":"MyCell"}}]

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

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

<rows>
	<row>
		<id>52c71040f14314a94e7ed14f</id>
		<list>1234567890</list>
		<added>1388771536</added>
		<modified>1388777536</modified>
		<version>5</version>
		<cells>
			<cell>
				<key>c1</key>
				<value>MyCell</value>
			</cell>
		</cells>
	</row>
</rows>

Adding Rows

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

Rows are added by creating a JSON object (example below) and submitting a POST with the field name "rows" 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 row object. Each row object must contain an array of "cells", the "list" id where were going to add the rows, and a "ref" field. 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 row is not added multiple times, so make sure you send a unique identifier as the "ref" for each new row.

http://api.toodledo.com/3/rows/add.php
	access_token=yourtoken
	rows=[{"list":"abcdef1234567890","cells":{"c1"=>"MyText"},"ref":"123456"}]

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

[{"id":"52c6f4b2f143145c197ed13d","added":1388770482,"modified":1388770482,"version":1,
"ref":"123456","list":"abcdef1234567890","cells":{"c1":"MyText"}}]

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

http://api.toodledo.com/3/rows/add.php
	access_token=yourtoken
	f=xml
	list=abcdef1234567890
	rows=[{"list":"abcdef1234567890","cells":{"c1"=>"MyText"},"ref":"123456"}]


<rows>
	<row>
		<id>52c6f9c8f14314ac4e7ed149</id>
		<ref>123456</ref>
		<added>1388771784</added>
		<modified>1388771784</modified>
		<version>1</version>
		<list>abcdef1234567890</list>
		<cells>
			<cell>
				<key>c1</key>
				<value>MyText</value>
			</cell>
		</cells>
	</row>
</rows>

Editing Rows

You can edit up to 50 rows at a time by making a POST to the "rows/edit.php" API call with the "rows" field set to an array of rows to edit. For each row edited, the "id" and "cells" fields are required.

Rows 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 row object.

http://api.toodledo.com/3/rows/edit.php
	access_token=yourtoken
	rows=[{"id":"52ab70f7f143149317ef5d38","list":"abcdef1234567890","version":"2","cells":{"c1":"mydata","c2"=>100}}]

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

[{"id":"52ab70f7f143149317ef5d38","added":1389048573,"modified":1389048573,"version":3,"list":"abcdef1234567890",
"cells":{"c1":"mydata","c2":100}}]

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

http://api.toodledo.com/3/rows/edit.php
	access_token=yourtoken
	f=xml
	rows=[{"id":"52ab70f7f143149317ef5d38","list":"abcdef1234567890","version":"2","cells":{"c1":"mydata","c2"=>100}}]


<rows>
	<row>
		<id>52cb35e7f14314ac54e96a31</id>
		<added>1389049319</added>
		<modified>1389049320</modified>
		<version>2</version>
		<list>52cb35e7f14314c654e96a41</list>
		<cells>
			<cell>
				<key>c1</key>
				<value>testEditXML2</value>
			</cell>
			<cell>
				<key>c2</key>
				<value>100</value>
			</cell>
		</cells>
	</row>
</rows>

Deleting Rows

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

Rows are deleted by submitting a JSON encoded array to the API. Each object in the array will contain the list id and the row id

http://api.toodledo.com/3/rows/delete.php
	access_token=yourtoken
	rows=[{"list":"1234abc"%2C"row":"abcde123"},{"list":"1234abc"%2C"row":"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":"abcde123"},{"errorCode":1007,"errorDesc":"Invalid row 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
	rows=[{"list":"1234abc"%2C"row":"abcde123"},{"list":"1234abc"%2C"row":"1235def"}]

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

Get Deleted Rows

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

  • list : The id number for the list that owns this row.
  • after : A GMT unix timestamp. Used to find rows with a deletion date and time after this date and time.

http://api.toodledo.com/3/rows/deleted.php&access_token=yourtoken&list=abcdef123&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/rows/deleted.php?access_token=yourtoken&list=abcdef123&after=1234567890&f=xml

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

  • 1001 : Row had no cells
  • 1002 : Only 50 rows can be added/edited/deleted at a time.
  • 1003 : Max rows reached
  • 1004 : Empty id / nothing sent
  • 1005 : Invalid list
  • 1006 : Nothing was added/edited
  • 1007 : Invalid row
  • 1009 : Row already added
  • 1011 : Malformed request
  • 1012 : Reference was empty
  • 1013 : Invalid cells format
  • 1014 : 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>