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.

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.

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.

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.

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.

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.

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.

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}