Developer's API Documentation : Collaboration

Overview

There are currently two ways to collaborate via the API. You can reassign a task to someone else by using the tasks/reassign.php call. This will move the task from one account to another. The other way to collaborate via the API is with jointly shared tasks. The owner of a task can choose to share it with their collaborators. The task will appear on everyone's list and be editable by anyone. You create a jointly shared task via the tasks/share.php call. Please review our sharing documentation for an overview of the concepts.

Jump To:

Retrieving Collaborators

To use Toodledo's collaboration tool, you first need a list of the user's collaborators. This is done via a GET or POST request to the "account/collaborators.php" API endpoint. This will give you useful information about the people that your user has permission to collaborate with.

http://api.toodledo.com/3/account/collaborators.php?access_token=a1b2c3d4e5f6a1b2c3d4e5f6

If the lookup was successful list of records will be returned.

JSON: 
[{"id":"1234abc","name":"Bob","reassignable":0,"sharable":1},{"id":"5678xyz","name":"Jane","reassignable":1,"sharable":0}]

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

http://api.toodledo.com/3/account/collaborators.php?access_token=a1b2c3d4e5f6a1b2c3d4e5f6&f=xml


XML: 

<users>
<user>
<id>1234abc</id>
<name>Bob</name>
<reassignable>0</reassignable>
<sharable>1</sharable>
</user>
<user>
<id>5678xyz</id>
<name>Jane</name>
<reassignable>1</reassignable>
<sharable>0</sharable>
</user>
</users>

The values returned have the following definitions:

  • id : The user id of the person.
  • name : The name of the person.
  • reassignable : A boolean (0 or 1) if this user can be reassigned a task.
  • sharable : A boolean (0 or 1) if this user can have jointly shared tasks.

Reassign a Task

The "/tasks/reassign.php" API call will enable you to reassign a task to a collaborator. You can access this via POST. This function is only available to accounts with a Subscription.

  • id : The id number of the task being reassigned.
  • assign : The user id that it is being reassigned to. Before you call this, be sure that the user has permission to be reassigned a task (has a 1 in the reassignable field from tasks/collaborators.php)

http://api.toodledo.com/3/tasks/reassign.php
	id=1234
	assign=td56789abcd
	access_token=yourtoken

If the reassignment was successful, the task id will be echoed back to you. If there was an error, it will be printed (see below). A reassignment can fail if the user does not have permission to reassign the task, or if the task is already shared jointly. Once the task has been successfully reassigned, it will be deleted from the current user's account by appearing in calls to /tasks/deleted.php.

{"reassigned":1234}


<reassigned>1234</reassigned>

Share a Task

The "/tasks/share.php" API call will enable you to jointly share a task with any number of collaborators. They can edit the task and the changes will be reflected in everyone's account. You can access this via POST. This function is only available to accounts with a Subscription. Only the owner of a task can make changes to how a task is shared.

  • id : The id number of the task being shared.
  • share : A JSON encoded array of user ids to share the task with. To unshare a tasks with someone, remove their user id from the list and resubmit this query. To unshare the task with everyone, submit an empty array.

http://api.toodledo.com/3/tasks/share.php
	access_token=yourtoken
	id=1234
	share=["td56789abcd"%2C"td12345xyz"]

If the share was successful, the task id will be echoed back to you. If there was an error, it will be printed (see below). A share can fail if the user does not have permission to share the task.

{"shared":1234}


<shared>1234</shared>

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 account API.

  • 1 : No access token was given. Read More...
  • 2 : The access token was invalid.
  • 3 : Too many API requests. Read More...
  • 4 : The API is offline for maintenance.
  • 604 : Empty id
  • 615 : Invalid collaborator
  • 616 : Unable to reassign or share task
  • 617 : Requires Toodledo subscription


Examples: 
{"errorCode":1,"errorDesc":"No access token"}


<error id="1">No access token</error>