Developer's API Documentation : Notes

Overview

The Notes section of Toodledo (sometimes called Notebook) is an entire section for long form notes that users can create. Notes can be organized into folders. Don't confuse this with the smaller notes that can be attached to a task.

Jump To:

Retrieving Notes
Adding Notes
Editing Notes
Deleting Notes
Get Deleted Notes
Errors

Syncing

If you use the following recommendations you can sync notes cleanly and efficiently. One of the most important things is to use the "lastedit_note" and "lastdelete_note" timestamps, 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.

Note Datatypes

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

id : The server id number for this note. It is guaranteed to be unique per account, but two different accounts may have two different notes with the same id number.
title : A string for the name of the note. Up to 255 characters.
folder : The id number of the folder. Omit this field or set it to 0 to leave the note unassigned to a folder.
modified : A GMT unix timestamp for when the note was last modified.
added : A GMT unix timestamp for when the note was added.
private : A boolean (0 or 1) that indicates if the note is flagged as a private entry. Currently, the website ignores this flag, but you may choose to provide additional security for private note entries.
text : A text string up to 62,000 bytes long. New lines should be sent as \n.

Retrieving Notes

The "notes/get.php" API call will return a list of the notes that match your search parameters. You can access this via GET or POST. The following search parameters may be used to limit the returned notes. To make sync go as efficiently as possible you should request the minimum amount of data that you need. Usually, this means keeping track of the "lastedit_note" field from the account/get.php API call and using this in combination with the "after" field in this call to request only those notes that have changed since your last sync.

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

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

[{"num":2,"total":2}, {"id":1234,"title":"My Ideas","modified":1281990824,
"added":1281990824,"folder":123,"private":0,"text":"The text of my note"},
{"id":1234,"title":"Favorite Movies","modified":1281990824,
"added":1281990824,"folder":123,"private":0,"text":"Star Wars"}]

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

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

 
<notes num="2" total="2">
	<note>
		<id>1234</id>
		<title>My Ideas</title>
		<folder>123</folder>
		<private>0</private>
		<modified>1234567890</modified>
		<added>1234567890</added>
		<text>The text of my note</text>
	</note>
	<note>
		<id>1235</id>
		<title>Favorite Movies</title>
		<folder>123</folder>
		<private>0</private>
		<modified>1234567890</modified>
		<added>1234567890</added>
		<text>Star Wars</text>
	</note>
</notes>

Adding Notes

You can add up to 50 notes at a time by making a POST to the "notes/add.php" API call. For each note, you can set the following fields: title, folder, private, added, text.

There is also a special field called "ref" that you can use to pass through an id number to aid in matching things up after a sync. The "ref" field is not saved into the note, it is only echoed back to you on this call.

Notes are added 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 note object. You only need to set the fields that you want to set. For efficiency, you should try to send only the fields that you are setting.

http://api.toodledo.com/3/notes/add.php
	access_token=yourtoken
	notes=[{"title"%3A"My Ideas"}%2C{"title"%3A"Favorite Movies"%2C
	"folder"%3A"123"%2C"text"%3A"Star Wars"%2C"ref"%3A"98765"}%2C{"ref"%3A"4567"}]

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

[{"id":1234,"title":"My Ideas","modified":1281990824,
"added":1281990824,"folder":123,"private":0,"text":"The text of my note"},
{"id":1234,"title":"Favorite Movies","modified":1281990824,
"added":1281990824,"folder":123,"private":0,"text":"Star Wars","ref":"98765"},
{"errorCode":701,"errorDesc":"Your note must have a name","ref":"4567"}]

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

http://api.toodledo.com/3/notes/add.php
	access_token=yourtoken
	f=xml
	notes=[{"title"%3A"My Ideas"}%2C{"title"%3A"Favorite Movies"%2C
"folder"%3A"123"%2C"text"%3A"Star Wars"%2C"ref"%3A"98765"}%2C{"ref"%3A"4567"}]

 
<notes>
	<note>
		<id>1234</id>
		<title>My Ideas</title>
		<folder>123</folder>
		<private>0</private>
		<modified>1234567890</modified>
		<added>1234567890</added>
		<text>The text of my note</text>
	</note>
	<note>
		<id>1235</id>
		<title>Favorite Movies</title>
		<folder>123</folder>
		<private>0</private>
		<modified>1234567890</modified>
		<added>1234567890</added>
		<text>Star Wars</text>
		<ref>98765</ref>
	</note>
	<error id="701" ref="4567">Your note must have a name</error>
</notes>

Editing Notes

You can edit up to 50 notes at a time by making a POST to the "notes/edit.php" API call. For each note, the id field is required, and the following fields are optional: title, folder, private, text (see above for possible values).

Notes 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 note object. You only need to set the fields that you want to edit. For efficiency, you should try to send only the fields that have changed.

http://api.toodledo.com/3/notes/edit.php
	access_token=yourtoken
	notes=[{"id"%3A"1234"%2C"title"%3A"My Note"}%2C{"id"%3A"1235"%2C"title"%3A
	"Favorite Movie"%2C"folder"%3A"123"}%2C{"id"%3A"5678"%2C"title"%3A"Does not exist"}]

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

[{"id":1234,"title":"My Ideas","modified":1281990824,
"added":1281990824,"folder":123,"private":0,"text":"The text of my note"},
{"id":1234,"title":"Favorite Movies","modified":1281990824,
"added":1281990824,"folder":123,"private":0,"text":"Star Wars"},{"errorCode":705,"errorDesc":"Invalid notebook ID","ref":"1235"}]

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

http://api.toodledo.com/3/notes/edit.php
	access_token=yourtoken
	f=xml
	notes=[{"id"%3A"1234"%2C"title"%3A"My Note"}%2C{"id"%3A"1235"%2C"title"%3A
	"Favorite Movie"%2C"folder"%3A"123"}%2C{"id"%3A"5678"%2C"title"%3A"Does not exist"}]

 
<notes>
	<note>
		<id>1234</id>
		<title>My Note</title>
		<folder>123</folder>
		<private>0</private>
		<modified>1234567890</modified>
		<added>1234567890</added>
		<text>The text of my note</text>
	</note>
	<note>
		<id>1235</id>
		<title>Favorite Movie</title>
		<folder>123</folder>
		<private>0</private>
		<modified>1234567890</modified>
		<added>1234567890</added>
		<text>Star Wars</text>
	</note>
	<error id="705" ref="1235">Invalid notebook ID</error>
</notes>

Deleting Notes

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

Notes are deleted by submitting a JSON encoded array of id numbers to the API.

http://api.toodledo.com/3/notes/delete.php
	access_token=yourtoken
	notes=[1234%2C1235]

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

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

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

http://api.toodledo.com/3/notes/delete.php
	f=xml
	access_token=yourtoken
	notes=[1234%2C1235]

<deleted>
	<id>1234</id>
	<error id="705" ref="1235">Invalid ID number</error>
</deleted>

Get Deleted Notes

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

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

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

This returns a list of id numbers and datetime stamps.

[{"num":24},{"id":1234,"stamp":1234567891},{"id":1235,"stamp":1234567892}]

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

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

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

701 : Your note must have a name.
702 : Only 50 notes can be added/edited/deleted at a time.
703 : The maximum number of notes allowed per account (10000) has been reached.
704 : Empty id supplied
705 : Invalid note or note not found
706 : Nothing was edited. You'll get this error if you attempt to edit a note but don't pass any parameters to edit.
707 : Invalid folder id
708 : Malformed request

Examples:

JSON:
{"errorCode":701,"errorDesc":"Your note must have a name","ref":1234}

XML:
<error id="701" ref="1234">Your note must have a name</error>