Developer's API Documentation : Goals

Overview

Goals are a way to organize tasks. Most people use goals to indicate how tasks contribute to longer term goals or aspirations. For example, a goal may be "get a promotion" and may contain tasks that the user thinks will get them there.

Jump To:

Syncing

Syncing goals is fairly straight forward. The first thing to do is add any new goals you have created and delete any goals that you have deleted. Then, look at the "lastedit_goal" timestamp returned from Account Info to determine if any changes have happened on the server since the last time you synced. If yes, then you need to fetch the goals from the server and integrate this into your local copy. This is where you would do conflict resolution if a goal was edited in both places. After this, if you have any goals that you edited, you can send these edits up to the server.

Sync Flowchart

Retrieving Goals

The "goals/get.php" API call will return a list of your goals. You can access this via GET or POST.

http://api.toodledo.com/3/goals/get.php?access_token=yourtoken

This call will return a JSON encoded object that looks like this.

[{"id":123,"name":"Get a Raise","level":0,"archived":1,"contributes":0,"note":""},
{"id":456,"name":"Lose Weight","level":0,"archived":0,"contributes":0,"note":"hi"},
{"id":789,"name":"Exercise","level":1,"archived":0,"contributes":456,"note":""}]

You can also specify xml as the output format for any API calls by attaching "f=xml" to the URL.

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


<goals>
	<goal>
		<id>123</id>
		<name>Get a Raise</name>
		<level>0</level>
		<archived>1</archived>
		<private>0</private>
		<contributes>0</contributes>
		<note>hi</note>
	</goal>
</goals>

Adding Goals

Add a goal using the "goals/add.php" API call. You can access this via POST. Goal names must be unique within an account. If you try to add a goal that already exists, you'll get an error. Each user can have up to 500 goals. If you try to add more than this, you will get an error.

  • name : A text string up to 250 characters. (required)
  • level : The integer 0, 1 or 2 specifying the level. The default is 0. (0=lifetime, 1=long-term, 2=short-term)
  • contributes : The id number for the higher level goal that this goal contributes to. If you send an invalid id, it will be reset to 0.
  • private : A boolean value (0 or 1) that describes if this goal can be shared. A value of 1 means that this goal is private.
  • note : A text string up to 32k bytes.

http://api.toodledo.com/3/goals/add.php
	name=MyGoal
	access_token=yourtoken

If the add was successful the new goal will be returned.

[{"id":12345,"name":"MyGoal","level":0,"archived":0,"contributes":0,"private":0,"note":""}]


<goals>
	<goal><id>12345</id><name>MyGoal</name><level>0</level><archived>0</archived>
	<contributes>0</contributes><private>0</private><note></note></goal>
</goals>

Editing Goals

Edit a goal using the "goals/edit.php" API call. You can access this via POST. Goal names must be unique within an account. If you try to edit the goal name to one that already exists, you will get an error. If you try to edit the goal, but pass in the same values that already exist on the server, you will get an error. You should avoid making unnecessary edits.

  • id : The id number of the goal to edit. (required)
  • name : A text string up to 250 characters.
  • level : The integer 0, 1 or 2 specifying the level. The default is 0. (0=lifetime, 1=long-term, 2=short-term)
  • contributes : The id number returned for the higher level goal that this goal contributes to. If you send an invalid id, it will be reset to 0.
  • archived : A boolean value (0 or 1) that describes if this goal is archived.
  • private : A boolean value (0 or 1) that describes if this goal can be shared. A value of 1 means that this goal is private.
  • note : A text string up to 32k bytes.

http://api.toodledo.com/3/goals/edit.php
	id=12345
	name=MyGoal
	access_token=yourtoken

If the edit was successful the edited goal will be returned.

[{"id":12345,"name":"MyGoal","level":0,"archived":0,"contributes":0,"private":0,"note":""}]


<goals>
	<goal><id>12345</id><name>MyGoal</name><level>0</level><archived>0</archived>
	<contributes>0</contributes><private>0</private><note></note></goal>
</goals>

Deleting Goals

The "goals/delete.php" API call will allow you to permanently delete a goal. You can access this via POST. Any tasks that have this goal will have their goal set to "none".

  • id : The id number of the goal to delete. (required)

http://api.toodledo.com/3/goals/delete.php
	id=12345
	access_token=yourtoken

If the delete was successful you will get the following message.

{"deleted":12345}


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

  • 401 : Your goal must have a name.
  • 402 : A goal with that name already exists.
  • 403 : Max goal reached (500).
  • 404 : Empty id.
  • 405 : Invalid goal.
  • 406 : Nothing was edited.


Examples: 
{"errorCode":402,"errorDesc":"A goal with that name already exists","ref":1234}


<error id="402" ref="1234">A goal with that name already exists</error>