Task

The task object represents a single task which belongs to a user's checklist.

A task object contains the following fields:

Name Description
id A system unique task id
ownerId the account id of the owner of the task.
parentId The id of the parent task. If empty it is a top task (checklist)
topId The id of the top task. If empty it is a top task (checklist)
name the name of the task
created the date the task was created using ISO 8601
timestamp the timestamp for the task (last created/ changed) ISO 8601
status the status of the task.
importance the importance of the task. Valid values are: 0 (low) to 5 (normal) to 10 (high)
dueDate the due date of the task
dueDateTime the due date time of the task
reminderType the due reminder type
reminderValue the due reminder value
position the position of the task (order) within the group. 0 is the first position.
notes the task notes
excerpt excerpt (valid for public checklists only)
tips tips (valid for public checklists only)
medias All media attached to this task in comma separated ids format
picture The url of the associated picture. This is optional and only for checklists. Checklist pictures are to be used with templates and are therefore public by nature (anyone with their url can view)
isPublic is this task (and its children) public. Only valid for top tasks (checklist)
expertName the name of the expert. Only valid for public tasks
expertURL the URL of the expert's page. Only valid for public tasks
url the url of the task. Only valid for public tasks
shareCode the shared code of the task. Only valid for checklists that a link has been created for (see below private link)
tags comma separated list of category ids. Only valid for public tasks
language the language of the task. Only valid for public tasks
subTasks all tasks which are children of this task recursively
assignedTo the account id of the contact to which the task is assigned
sharedContacts comma separated list of the contacts this list is shared with
original optional parameter valid only for checklists that have been published (template). Provides info about the template and the channel
props a placeholder for additional task properties. E.g. price, quantity

Sample Task XML

<task>
  <id>123</id>
  <parentId>1</parentId>
  <topId>2</topId>
  <name>buy oranges</name>
  <created>2011-12-30T16:45:31Z</created>
  <timestamp>2011-12-31T16:55:31Z</timestamp>
  <status>0</status>
  <importance>5</importance>
  <dueDate>2011-12-30</dueDate>
  <dueDateTime>15:39</dueDateTime>
  <dueReminderType>days</dueReminderType>
  <dueReminderValue>5</dueReminderValue>
  <reminderType>daily</reminderType>
  <position>24</position>
  <notes>Make sure they are round</notes>
  <excerpt>A checklist summary</excerpt>
  <tips>Tips for getting things done</tips>
  <reminder>30 minutes</reminder>
  <medias>123,456,789</medias>
  <picture>http://media.checklist.com/channels/pictures/buy-oranges.png</picture>
  <isPublic>true</isPublic>
  <expertName>George Bush</expertName>
  <expertURL>george-bush</expertURL>
  <url>buy-oranges</url>
  <shareCode>http://checklist.com/link/788ds7ds312a</shareCode>
  <tags>1,2,3,4,5</tags>
  <language>en</language>
  <ownerContactId>555</ownerContactId>
  <assignedTo>1234567890</assignedTo>
  <sharedContacts>1,2,3,4</sharedContacts>
  <original>
    <templateName>Moving checklist</templateName>
    <templateUrl>http://checklist.com/moving-checklist</templateUrl>
    <image>http://media.checklist.com/channels/pictures/5432fsagds.png</image>
    <channelName>John Smith</channelName>
    <channelUrl>http://checklist.com/channels/john-smith</channelUrl>
  </original>
  <props>
    <name>price</name><value>100</value>
	<name>currency</name><value>USD</value>
  </props>
  <tasks>
    <task>

    </task>
    <task>

    </task>
  </tasks>
</task>

Supported methods

Get list

Method list
Description Get the tasks (top level checklists) for a user including statistics for main dashboard. This is a heavy request and should be called only once the client is loaded. A user may trigger a call to refresh the list.
URL https://api.checklist.com/rest/v1/tasks/list [GET]
Authentication required
Parameters
Response A list of top level tasks (checklists) where each also includes the number of open tasks in it. Additionally the following values for the filters (this includes only open tasks): today (today and 6 days back), important, coming up (tomorrow and 6 more days ahead) and per contact (assigned).
Errors 401UnAuthorized - returned if user is not authorized on our system
Throttling normal

Get

Method get
Description Returns the specified task object including its children.
URL https://api.checklist.com/rest/v1/tasks/{taskId} [GET]
Authentication required
Parameters taskIdthe id of the task to return
Response The task is returned with any eventual sub tasks
Errors 401UnAuthorized - returned if user is not authorized on our system
404Not Found - returned if provided checklist id is invalid
Throttling normal

Add

Method add
Description Create a new task and add it to the user's checklist under the specified task (or in root) and in the correct position. Note that if any of the optional parameters are given and are invalid, the API does its best to accommodate. Always check the returned task to ensure your call was processed.
URL https://api.checklist.com/rest/v1/tasks/add?name={name}&destination={destination}&position={position} [POST]
Authentication required
Parameters destinationthe id of the parent task. If empty will add the task at the top level (as a checklist)
namethe name of the task. Maximum 255 characters
positionthe position of the task within the group (i.e. the parent subtasks).
Response The newly created task is returned
Errors 400Invalid Parameters - returned if provided task name is invalid (Length>=0)
400Invalid Parameters - returned if provided position is invalid (pos >= 0)
401UnAuthorized - returned if user is not authorized on our system
404Not Found - returned if provided parent id is invalid
Throttling normal

Update status

Method status
Description Update the status of the task. Changing a task to open, completed or deleted will automatically mark all of its sub tasks the same.
URL https://api.checklist.com/rest/v1/tasks/{taskId}/status?status={status} [PUT]
Authentication required
Parameters taskIdthe id of the task to be marked as completed
statusthe status to change into. Possible options are open (0), completed (1) or deleted (-1)
Response Status200 - OK
Errors 400Invalid- returned if the status is not 0,1 or -1
401UnAuthorized - returned if user is not authorized
404Not Found - returned if provided task id is invalid
Throttling normal

Update Importance

Method importance
Description Update the importance of the task. Tasks are set to normal importance by default
URL https://api.checklist.com/rest/v1/tasks/{taskId}/importance?importance={importance} [PUT]
Authentication required
Parameters taskIdthe id of the task to be marked as completed
importancethe importance to change into. Possibly options 0 (low) 5 (default, normal) and 10 (high)
Response Status200 - OK
Errors 400Invalid- returned if the importance is a valid value
401UnAuthorized - returned if user is not authorized
404Not Found - returned if provided task id is invalid
Throttling normal

Name

Method name
Description Set the name of the task (rename)
URL https://api.checklist.com/rest/v1/tasks/{taskId}/name?name={name} [PUT]
Authentication required
Parameters taskIdthe id of the task
namethe new name for the task. Max 255 characters long
Response 200 - OK
Errors 400Invalid Parameters - returned if provided task name is invalid (Length>0)
401UnAuthorized - returned if user is not authorized
404Not Found - returned if provided task id is invalid
Throttling normal

Notes

Method/b> notes
Description Sets the notes of the task. If the notes parameter is empty, the notes will be cleared (i.e. deleted))
URL https://api.checklist.com/rest/v1/tasks/{taskId}/notes?notes={notes} [PUT]
Authentication required
Parameters taskIdthe id of the task
notesthe new notes for the task. Maximum length is 5000 characters. No HTML tags are allowed.
Response 200 - OK
Errors 400Invalid- returned if the note is invalid (i.e. length>5000)
401UnAuthorized - returned if user is not authorized
404Not Found - returned if provided task id is invalid
Throttling normal

Excerpt

Method excerpt
Description Sets the excerpt of the checklist. This is only valid for public checklists (not tasks). Place here a short summary of what the checklist is about.
URL https://api.checklist.com/rest/v1/tasks/{taskId}/excerpt?excerpt={excerpt} [PUT]
Authentication required
Parameters taskIdthe id of the task
excerptthe new notes for the task. Maximum length is 255 characters. No HTML tags are allowed.
Response 200 - OK
Errors 400Invalid- returned if the excerpt is invalid (i.e. length>255)
401UnAuthorized - returned if user is not authorized
404Not Found - returned if provided task id is invalid
Throttling normal

Tips

Method tips
Description Sets the tips of the checklist. This is only valid for public checklists (not tasks). Place here tips to help the user get things done with this checklist.
URL https://api.checklist.com/rest/v1/tasks/{taskId}/excerpt?excerpt={excerpt} [PUT]
Authentication required
Parameters taskIdthe id of the task
excerptthe new notes for the task. Maximum length is 5000 characters. Basic HTML tags are allowed (no links).
Response 200 - OK
Errors 400Invalid- returned if the tips are invalid (i.e. length>5000)
401UnAuthorized - returned if user is not authorized
404Not Found - returned if provided task id is invalid
Throttling normal

Move Task

Method move
Description Move a task to a new position. The position can be anywhere within the group (the sub tasks of the parent) or to a completely new checklist or as a new checklist. The count starts at 0. Task owners cannot be changed. Only checklist owners can move a checklist.
URL https://api.checklist.com/rest/v1/tasks/{taskId}/move?destination={destination}&position={position} [PUT]
Authentication required
Parameters taskIdthe id of the task
destinationthe id of the new parentId (or the same parent)
positionthe new position of the task
Response 200 - OK
Errors 400Invalid Parameters - returned if provided position is invalid (pos >= 0) or outside the number of tasks in the group
401UnAuthorized - returned if user is not authorized
404Not Found - returned if provided task id is invalid
Throttling normal

Due Date & Time

Method due
Description Set the due date & time for the task. If the dueDateTime parameter is passed empty, the dueDate is cleared from the task. In case the due time is not passed, the system will use the user's default time of day for reminders (defaults to 08:00).
URL https://api.checklist.com/rest/v1/tasks/{taskId}/due?date={date}&time={time}&reminderTerm={mins|hours|days|weeks|months}&reminderValue={x} [PUT]
Authentication required
Parameters taskIdthe id of the task
datethe due date in this format: YYYY-MM-DD (e.g. 2012-12-31)
timethe due time in this format: HH:mm (e.g. 13:45)
reminderTermthe type of reminder to be set. Valid values are: mins|hours|days|weeks|months
reminderValuethe value associated with the reminder term as a positive integer
Response 200 - OK
Errors 400Invalid Parameters - returned if provided date is invalid
400Invalid Parameters - returned if provided date is invalid
400Invalid Parameters - returned if provided reminderType is invalid
400Invalid Parameters - returned if provided reminderValue is invalid
401UnAuthorized - returned if user is not authorized
404Not Found - returned if provided task id is invalid
Throttling normal

Reminder

Method reminder
Description Set the reminders for the task. If any parameters are missing, the reminder will be cleared
URL https://api.checklist.com/rest/v1/tasks/{taskId}/reminder?type={type}&when={when} [PUT]
Authentication required
Parameters taskIdthe id of the task
typevalid values are daily | weekly | monthly | annually
whenwhen should the reminder be sent in respect of the type. Valid options are hh:mm | days.of.week | dd-mm (day-month) - respectively. Days of the week are from 1 until 7 (SUN-SAT)
Response 200 - OK
Errors 400Invalid Parameters - returned if provided type is invalid
400Invalid Parameters - returned if provided when is invalid
401UnAuthorized - returned if user is not authorized
404Not Found - returned if provided task id is invalid
Throttling normal

Share

Method share
Description Share the task with a contact. The contact does not have to already be active i.e. an invitation has been sent but not accepted yet. Only top tasks (i.e. checklists) can be shared. The contact will have complete access to the task and its subtasks except for sharing and deleting the top tasks.
URL https://api.checklist.com/rest/v1/tasks/{taskId}/share?contactId={contactId} [PUT]
Authentication required
Parameters taskIdthe id of the task to be shared
contact idthe id of the contact the user wishes to share the task with
Response 200 - OK
Errors 400Invalid Parameters - returned if provided type is invalid
400Invalid Parameters - the task is not a top task (i.e. not a checklist)
401UnAuthorized - returned if user is not authorized
404Not Found - returned if provided task id is invalid
Throttling normal

UnShare

Method unshare
Description Stop sharing the task with a contact. The contact will no longer have access to the task or its sub tasks.
URL https://api.checklist.com/rest/v1/tasks/{taskId}/unshare?contactId={contactId} [DELETE]
Authentication required
Parameters taskIdthe id of the task
contact idthe id of the contact the user wishes to stop sharing the task with
Response 200 - OK
Errors 400Invalid Parameters - returned if provided type is invalid
401UnAuthorized - returned if user is not authorized
404Not Found - returned if provided task id is invalid or the task is not shared with this contact
Throttling normal

Duplicate

Method duplicate
Description Make a fresh copy of the task (duplicate) and its sub tasks. Any shared contacts are stripped off. In addition, if the task is public and user is not the owner, any media is copied to the new user's account (barring any media limits).
URL https://api.checklist.com/rest/v1/tasks/{taskId}/duplicate?destination={destination}&position={position} [POST]
Authentication required
Parameters taskIdthe id of the task to be duplicated
destinationthe id of the task under which the task should be duplicated. If left empty, the new task will be placed in the top level (checklist)
positionthe position in the destination (relevant to its siblings)
Response The new copy of the task
Errors 401UnAuthorized - returned if user is not authorized on our system
404Not Found - returned if provided task id is invalid
404Not Found - returned if provided parent id is invalid
Throttling normal

Assign To

Method assignTo
Description Assign a task to one of the contacts the task is shared with. By default, all tasks are assigned to their owner. It is only possible to assign a task to a contact that has already accepted the invitation (active) and is sharing the checklist. The contact will then have an account id. This action is non-recursive (i.e. the children of the task will NOT be changed assignee).
URL https://api.checklist.com/rest/v1/tasks/{taskId}/assignTo?accountId={accountId} [PUT]
Authentication required
Parameters taskIdthe id of the task to be assigned
accountIdthe account id of the contact to assign the task to. Must be a contact with whom the task has already been shared with.
Response 200 - OK
Errors 401UnAuthorized - returned if user is not authorized on our system
404Not Found - returned if provided task id is invalid
404Not Found - returned if provided contact id is invalid
Throttling normal

Publish

Method publish
Description Publish the task and share it with the world. The task will become available on our portal for others to work with. Only top tasks can be published and any media they have attached will become public.
URL https://api.checklist.com/rest/v1/tasks/{taskId}/publish?tags={tag1, tag2,.. tagx}&url={url}&language={language} [POST]
Authentication required
Parameters taskIdthe id of the task
tagscomma separated list of tags under which the task should be shared. At least one is required.
urlThe url to be published under. This is treated as a request and could be changed by the system. The url will be made SEO friendly (i.e. only letters and numbers, all small letters and spaces will be converted into dashes.
langIf no language is provided, the system will assign one the language under which the task should be published (the user's). Must be one of the languages supported by the platform.
Response The published task (top level only)
Errors 400Invalid Parameters - returned if provided categories are invalid
400Invalid Parameters - returned if provided url is invalid and cannot be fixed
401UnAuthorized - returned if user is not authorized
404Not Found - returned if provided contact id is invalid
Throttling normal

Un-Publish

Method unpublish
Description Stop publishing the task and make it private again. Any related media that is no longer shared publicly elsewhere is made private again.
URL https://api.checklist.com/rest/v1/tasks/{taskId}/unpublish [DELETE]
Authentication required
Parameters taskIdthe id of the checklist
Response 200 - OK
Errors 401UnAuthorized - returned if user is not authorized
404Not Found - returned if provided task id is invalid
Throttling normal
Method getLink
Description creates a private link to the checklist that can be used to access it. Can only be applied to top level tasks (checklists)
URL https://api.checklist.com/rest/v1/tasks/{taskId}/link [PUT]
Authentication required
Parameters taskIdthe id of the task
Response the checklist object with an updated share code in it
Errors 401UnAuthorized - returned if user is not authorized
404Not Found - returned if provided task id is invalid
Throttling normal
Method deleteLink
Description Removes the link effectively making the task un-accessible via this link any longer
URL https://api.checklist.com/rest/v1/tasks/{taskId}/link [DELETE]
Authentication required
Parameters taskIdthe id of the task
Response The updated task object with no share code in it
Errors 401UnAuthorized - returned if user is not authorized
404Not Found - returned if provided task id is invalid
Throttling normal

Media

Method media
Description Attach media objects to the tasks. If passed empty it will clear all medias attached to the task (but will not delete them from the account).
URL https://api.checklist.com/rest/v1/tasks/{taskId}/media?ids={media_id_1, ... , media_id_x} [PUT]
Authentication required
Parameters taskIdthe id of the task
idscomma separated list of media ids. The order is maintained.
Response 200 - OK
Errors 401UnAuthorized - returned if user is not authorized
404Not Found - returned if provided task id is invalid
Throttling normal

Set Picture

Method setPicture
Description Uploads the checklist's picture. If a picture already exists it will be overwritten. The following limitations apply: max size 700kb and types: jpg, png, bmp or gif. A picture should have the size: 300x163 px.
URL https://api.checklist.com/rest/v1/tasks/{taskId}/picture [POST]
Authentication Required
Parameters filepassed in the body of the request
Response 200The url where the image is available
Errors 401UnAuthorized - returned if not authorized to perform this action.
Throttling normal

Delete Picture

Method deletePicture
Description Removes the checklists's picture.
URL https://api.checklist.com/rest/v1/tasks/{taskId}/picture [DELETE]
Authentication Required
Parameters
Response 200OK
Errors 401UnAuthorized - returned if not authorized to perform this action.
Throttling normal

Get Important list

Method listImportant
Description Gets a flat list of tasks which are open and are marked important. The tasks will be sorted by Due date in a descending order.
URL https://api.checklist.com/rest/v1/tasks/listImportant?max={max|25} [GET]
Authentication required
Parameters maxthe maximum number of tasks to return.
Response A flat list of tasks.
Errors 401UnAuthorized - returned if user is not authorized on our system
Throttling normal

Get Open list

Method listOpen
Description Gets a flat list of tasks which are open. The tasks will be sorted by Due date in a descending order.
URL https://api.checklist.com/rest/v1/tasks/listOpen?max={max|25} [GET]
Authentication required
Parameters maxthe maximum number of tasks to return.
Response A flat list of tasks.
Errors 401UnAuthorized - returned if user is not authorized on our system
Throttling normal

Get Due list

Method listDue
Description Gets a flat list of tasks which are open and have a due date. E.g. this can be used to return the tasks that are open today or coming up in the next week
URL https://api.checklist.com/rest/v1/tasks/listDue?date={date}&offset={offset}&max={max|25} [GET]
Authentication required
Parameters datethe date in ISO 8601 format to start the filter from the number of seconds to limit from the date.
offsetThis can be a positive or negative number (going backwards or forwards in time) of seconds. If positive the order returned is ascending, otherwise descending.
maxthe maximum number of tasks to return.
Response A flat list of tasks.
Errors 401UnAuthorized - returned if user is not authorized on our system
Throttling normal

Update Property

Method prop
Description Updates the value of a proprty. If was empty before it will be added. If an empty value is passed, the property will be removed.
URL https://api.checklist.com/rest/v1/tasks/{taskId}/prop?name={name}&value={value} [PUT]
Authentication required
Parameters nameThe name of the property. Length 3-128
valueThe value to be set. Empty to remove property.
Response Status200 - OK
Errors 401UnAuthorized - returned if user is not authorized on our system
Throttling normal
* - optional parameter.   | x - x is the default value if none provided   Back to list of Checklist API Objects