Tasks

Tasks API

Scope: ZohoProjects.tasks.{Operation}

Operations: READ, CREATE, UPDATE, DELETE, ALL

Use the ALL operation to gain the scope for all the other operations like READ, CREATE, UPDATE, and DELETE at once.

All Tasks
GET  /portal/[PORTALID]/projects/[PROJECTID]/tasks/
Tasks for a Tasklist
GET  /portal/[PORTALID]/projects/[PROJECTID]/tasklists/[TASKLISTID]/tasks/
Task Details
GET  /portal/[PORTALID]/projects/[PROJECTID]/tasks/[TASKID]/
Create Task
POST  /portal/[PORTALID]/projects/[PROJECTID]/tasks/
Update Task
POST  /portal/[PORTALID]/projects/[PROJECTID]/tasks/[TASKID]/
Delete Task
DELETE /portal/[PORTALID]/projects/[PROJECTID]/tasks/[TASKID]/
Create Subtask
POST /portal/[PORTALID]/projects/[PROJECTID]/tasks/[TASKID]/subtasks/
Get Subtasks
GET /portal/[PORTALID]/projects/[PROJECTID]/tasks/[TASKID]/subtasks/
Get Comments
GET  /portal/[PORTALID]/projects/[PROJECTID]/tasks/[TASKID]/comments/
Add Comment
POST  /portal/[PORTALID]/projects/[PROJECTID]/tasks/[TASKID]/comments/
Update Comment
POST  /portal/[PORTALID]/projects/[PROJECTID]/tasks/[TASKID]/comments/[COMMENTID]/
Delete Comment
DELETE /portal/[PORTALID]/projects/[PROJECTID]/tasks/[TASKID]/comments/[COMMENTID]/
Get Task Attachments
GET  /portal/[PORTALID]/projects/[PROJECTID]/tasks/[TASKID]/attachments/
Delete Task Attachments
DELETE  /portal/[PORTALID]/projects/[PROJECTID]/tasks/[TASKID]/attachments/[ATTACHMENTID]/
Get All Task Layouts
GET  /portal/[PORTALID]/tasklayouts/
Get Task Layout Details
GET  /portal/[PORTALID]/projects/[PROJECTID]/tasklayouts/

 All Tasks

Gets all the tasks in the given project. It fetches only the main tasks and not the subtasks.

GET  /portal/[PORTALID]/projects/[PROJECTID]/tasks/

Scope: ZohoProjects.tasks.READ

Request Parameters

indexintIndex number of the task.
rangeint

Range of the tasks.

ownerString or Long

Owner of the task must be provided as all or user ID.

(all - String, user ID - Long)

statusStringStatus of the task must be all or completed or notcompleted.
timeStringTime period of the task must be all or overdue or today or tomorrow.
priorityStringPriority of the task must be all or none or low or medium or high.
tasklist_idLongId of the tasklist.
custom_statusLongThe ID of the custom task status. Example : 932200000000277068.

Sample Response

Status: 200 Success

Content Type: application/json;charset=utf-8
{
"tasks": [
{
"id": 170876000000270080,
"name": "Ledger",
"completed": true,
"created_by": "2060758",
"created_person": "Patricia Boyle",
"priority": "High",
"percent_complete": 100,
"start_date": "01-14-2011 12:00 AM",
"start_date_long": 1294972200000,
"end_date": "01-24-2011 12:00 AM",
"end_date_long": 1295836200000,
"custom_fields": [{
            "column_name": "UDF_CHAR1",
            "label_name": "My_date",
            "value": "Custom field example"
        }],
"dependency": {
"successor": [
"1234567899876543201"
],
"predecessor": [
"1239857339384756943"
]
},
"duration": "11",
"details": {
"owners": [
{
"name": "Amritha Agrawal",
"id": "2063270"
}
]
},
"link": {
"self": {
"url": "https://projectsapi.zoho.com/restapi/portal/2063927/projects/ 170876000000147021/tasks/170876000000270067/"
},
"timesheet": {
"url": "https://projectsapi.zoho.com/restapi/portal/2063927/projects/ 170876000000147021/tasks/170876000000270067/logs/"
}
},
"tasklist": {
"id": 170876000000270050,
"name": "ERP Phase III"
},
"status": {
            "name": "Open",
            "id": "4000000000335",
            "type": "open",
            "color_code": "#eb5768"
            }
}
]
}

 Tasks for a Tasklist

Gets all the tasks in the given tasklist .

GET  /portal/[PORTALID]/projects/[PROJECTID]/tasklists/[TASKLISTID]/tasks/

Scope: ZohoProjects.tasks.READ

Request Parameters

indexintIndex number of the task.
rangeintRange of the tasks.

Sample Response

Status: 200 Success

Content Type: application/json;charset=utf-8
{
    "tasks": [{
        "id": 170876000001217298,
        "name": "Fix review comments by SME",
        "completed": true,
        "created_by": "2060758",
        "created_person": "Patricia Boyle",
        "priority": "None",
        "percent_complete": 100,
        "start_date": "09-30-2013 12:00 PM",
        "start_date_long": 1380551400000,
        "end_date": "10-04-2013 09:00 PM",
        "end_date_long": 1380929400000,
        "duration": "49",
        "details": {
            "owners": [{
                "name": "Unassigned"
            }]
        },
        "link": {
            "self": {
                "url": "https://projectsapi.zoho.com/restapi/portal/2063927/projects/
                        170876000000147021/tasks/170876000001217298/"
            },
            "timesheet": {
                "url": "https://projectsapi.zoho.com/restapi/portal/2063927/projects/
                        170876000000147021/tasks/170876000001217298/logs/"
            }
        }
    }]
}

 Task Details

Gets all the details for the task.

GET  /portal/[PORTALID]/projects/[PROJECTID]/tasks/[TASKID]/

Scope: ZohoProjects.tasks.READ

Sample Response

Status: 200 Success

Content Type: application/json;charset=utf-8
{
    "tasks": [{
        "id": 170876000001217306,
        "name": "Send for language  review",
        "completed": false,
        "created_by": "2060758",
        "created_person": "Patricia Boyle",
        "priority": "None",
        "percent_complete": 50,
        "start_date": "04-15-2014 10:00 AM",
        "start_date_long": 1397565000000,
        "end_date": "04-24-2014 07:00 PM",
        "end_date_long": 1398375000000,
        "dependency":{
        "successor":["1234567899876543201"],
        "predecessor":["1239857339384756943"]
         },
        "duration": "8",
        "details": {
            "owners": [{
                "name": "Einhard Klein",
                "id": "2060761"
            }]
        },
        "link": {
            "self": {
                "url": "https://projectsapi.zoho.com/restapi/portal/2063927/projects/
                        170876000000147021/tasks/170876000001217306/"
            },
            "timesheet": {
                "url": "https://projectsapi.zoho.com/restapi/portal/2063927/projects/
                        170876000000147021/tasks/170876000001217306/logs/"
            }
        }
    }]
}

 Create Task

POST  /portal/[PORTALID]/projects/[PROJECTID]/tasks/

Scope: ZohoProjects.tasks.CREATE

Request Parameters

person_responsibleLongOwner ID of the task. User ID for multiple owners must be separated by commas.
tasklist_idLongID of the tasklist.
name*StringName of the task.
start_dateString [MM-DD-YYYY]Start date of the task.
end_dateString [MM-DD-YYYY]End date of the task.
duration intDuration of the task.
duration_typeStringDuration of the task type in days or hrs.
priority (None or Low or Medium or High)StringPriority of the task must be None or Low or Medium or High.
descriptionStringDescription for the task.
uploaddocFileAdd file to a task.
start_timeStringStart time can be specified in either 12 hour or 24 hour format. Eg. 01:00 pm or 13:00
end_timeStringEnd time can be specified in either 12 hour or 24 hour format. Eg. 09:00 pm or 21:00
owner_workJSON Arrayuser_id and working_hours must be given in the array to assign work hours to task owners. [{"user_id":"xxxxxx","working_hours":"2"}]
work_typeStringAllocate work_hrs_per_day or work_in_percentage or work_hours.
custom_fieldsJSON ObjectValue of the custom field. Example: {“UDF_CHAR1”:”Hello”}

Example of creating a task with custom fields

Since custom field <display_name> is not unique, custom fields are referred by their respective < column_name>. The same custom field <display_name> will be referred with different < column_name>. The params that you need to pass for the task custom fields is the value in <column_name> in Get Task Layout Details API. 

You must first get all the custom fields, and then pass the <column_name> value of the custom field as a param to create a task with the custom fields.

Example: {“UDF_CHAR1”:”Hello”}

UDF_CHAR1 is the param that you need to pass while creating tasks.

Hello is the value of the custom field. 

Here is a sample response of a custom field:

{
"section_name": "New Section",
"customfield_details": [{
"column_name": "UDF_CHAR1",
"is_mandatory": false,
"is_default": false",
"display_name": "My_Field",
"column_type": "singleline" }]
}

Sample Response

Status: 201 Created

Content Type: application/json;charset=utf-8
{
"tasks": [
{
"id": 170876000001849020,
"name": "Fix QA comments",
"completed": false,
"created_by": "2060758",
"created_person": "Patricia Boyle",
"priority": "None",
"percent_complete": 0,
"custom_fields": [{
            "column_name": "UDF_DATE1",
            "label_name": "My_date",
            "value": "11-11-2017 12:00:00 AM"
            }],
"details": {
"owners": [
{
"name": "Unassigned"
}
]
},
"link": {
"self": {
"url": "https://projectsapi.zoho.com/restapi/portal/2063927/projects/ 170876000000147021/tasks/170876000001849039/"
},
"timesheet": {
"url": "https://projectsapi.zoho.com/restapi/portal/2063927/projects/ 170876000000147021/tasks/170876000001849039/logs/"
}
},
"status": {
            "name": "Open",
            "id": "4000000000335",
            "type": "open",
            "color_code": "#eb5768"
            }
}
]
}

Note:

  • The task custom field feature is available only in the Enterprise plan.

 Update Task

Updates the task in the given project

POST  /portal/[PORTALID]/projects/[PROJECTID]/tasks/[TASKID]/

Scope: ZohoProjects.tasks.UPDATE

Request Parameters

person_responsible*LongOwner ID of the task. User ID for multiple owners must be separated by commas.
name*StringName of the task.
start_dateString [MM-DD-YYYY]Start date of the task.
end_dateString [MM-DD-YYYY]End date of the task.
percent_completeintTask completed percentage must be provided in multiple of 10's. [10 to 100]
durationintDuration of the task.
duration_typeStringDuration of the task type in days or hrs.
priority (None or Low or Medium or High) StringPriority of the task must be None or Low or Medium or High.
descriptionStringDescription for the task.
start_timeStringStart time can be specified in either 12 hour or 24 hour format. Eg. 01:00 pm or 13:00
end_timeStringEnd time can be specified in either 12 hour or 24 hour format. Eg. 01:00 pm or 13:00
owner_workJSON Arrayuser_id and working_hours must be given in the array to assign work hours to task owners.
work_typeStringAllocate work_hrs_per_day or work_in_percentage or work_hours.
task_duration_as_workStringAllocates entire task duration as work hours for the task owners if value is true
uploaddocFileAdd a file to the task.
custom_fieldsJSON ObjectValue of the custom field. Example : {"UDF_CHAR1":"Hello"}
custom_statusLongThe ID of the custom task status. Example : 932200000000277068

Example of updating task with custom fields.

Sample Response

Status: 200 Success

Content Type: application/json;charset=utf-8
{
"tasks": [
{
"id": 170876000001849020,
"name": "Fix QA comments",
"completed": false,
"created_by": "2060758",
"created_person": "Patricia Boyle",
"priority": "None",
"percent_complete": 0,
"custom_fields": [{
            "column_name": "UDF_DATE1",
            "label_name": "My_date",
            "value": "11-11-2017 12:00:00 AM"
            }],
"details": {
"owners": [
{
"name": "Unassigned"
}
]
},
"link": {
"self": {
"url": "https://projectsapi.zoho.com/restapi/portal/2063927/projects/ 170876000000147021/tasks/170876000001849039/"
},
"timesheet": {
"url": "https://projectsapi.zoho.com/restapi/portal/2063927/projects/ 170876000000147021/tasks/170876000001849039/logs/"
}
},
"status": {
            "name": "Open",
            "id": "4000000000335",
            "type": "open",
            "color_code": "#eb5768"
            }
}
]
}

Note:

  • The task custom field feature is available only in the Enterprise plan. 

 Delete Task

Deletes the tasks in the given project.

DELETE /portal/[PORTALID]/projects/[PROJECTID]/tasks/[TASKID]/

Scope: ZohoProjects.tasks.DELETE

Sample Response

Status: 200 Success

Content Type: application/json;charset=utf-8
{
    "response": "Task Deleted Successfully"
}

 Create Subtask

POST  /portal/[PORTALID]/projects/[PROJECTID]/tasks/[TASKID]/subtasks/

Scope: ZohoProjects.tasks.CREATE

Request Parameters

person_responsibleLongOwner ID of the task. User ID for multiple owners must be separated by commas.
name*StringName of the task.
start_dateString [MM-DD-YYYY]Start date of the task.
end_dateString [MM-DD-YYYY]End date of the task.
durationintDuration of the task.
duration_typeStringDuration of the task type in days or hrs.
priority (None or Low or Medium or High)StringPriority of the task must be None or Low or Medium or High.
descriptionStringDescription for the task.
custom_fieldsJSON ObjectValue of the custom field. Example: {“UDF_CHAR1”:”Hello”}

Example of creating a subtask with custom fields.

Sample Response

Status: 201 Created

Content Type: application/json;charset=utf-8
{
  "tasks": [{
  "created_by": "2060758",
  "created_time_long": 1451974141000,
  "subtasks": false,
  "link": {
  "self": {
  "url": "https://projectsapi.zoho.com/restapi/portal/zillum/projects/
   170876000001865067/tasks/170876000002969005/"
  },
  "timesheet": {
  "url": "https://projectsapi.zoho.com/restapi/portal/zillum/projects/
   170876000001865067/tasks/170876000002969005/logs/"
  }
  },
  "depth": 1,
  "last_updated_time_format": "01-04-2016 10:09:01 PM",
  "last_updated_time_long": 1451974141000,
  "id": 170876000002969005,
  "percent_complete": "0",
  "created_person": "Patricia Boyle",
  "last_updated_time": "01-04-2016",
  "details": {
  "owners": [{
  "name": "Unassigned"
  }]
  },
  "id_string": "170876000002969005",
  "priority": "None",
  "name": "Blog Image",
  "created_time_format": "01-04-2016 10:09:01 PM",
  "created_time": "01-04-2016",
  "completed": false
  }]
}

Note:

  • The task custom field feature is available only in the Enterprise plan.

 Get Subtasks

Get all the subtasks of the given task.

GET  /portal/[PORTALID]/projects/[PROJECTID]/tasks/[TASKID]/subtasks/

Scope: ZohoProjects.tasks.READ

Request Parameters

indexintIndex number of the subtask.
rangeintRange of the subtasks.

Sample Response

Status: 200 Success

Content Type: application/json;charset=utf-8
{
    "tasks": [{
        "created_by": "2060758",
        "subtasks": false,
        "start_date_long": 1408365000000,
        "link": {
            "self": {
                "url": "https://projectsapi.zoho.com/restapi/portal/2063927/projects/
                        170876000001865067/tasks/170876000001868770/"
            },
            "timesheet": {
                "url": "https://projectsapi.zoho.com/restapi/portal/2063927/projects/
                        170876000001865067/tasks/170876000001868770/logs/"
            }
        },
        "tasklist": {
            "id": 170876000001868599,
            "name": "ERP Phase III"
        },
        "depth": 1,
        "end_date_format": "08-19-2014 06:30 AM",
        "id": 170876000001868770,
        "percent_complete": "60",
        "duration": "2",
        "created_person": "Boyle Patricia",
        "end_date": "08-19-2014",
        "details": {
            "owners": [{
                "id": "2060556",
                "name": "Hiyoshi Nakano"
            }, {
                "id": "2060755",
                "name": "Manish Patel"
            }]
        },
        "priority": "None",
        "name": "Work on Finance Budget for this month",
        "end_date_long": 1408483800000,
        "start_date_format": "08-17-2014 09:30 PM",
        "start_date": "08-17-2014",
        "completed": false
    }]
}

 Get Comments

Get all the task comments. 

GET  /portal/[PORTALID]/projects/[PROJECTID]/tasks/[TASKID]/comments/

Scope: ZohoProjects.tasks.READ

Request Parameters

indexintIndex number of the task comment.
rangeintRange of the task comments.

Sample Response

Status: 200 Success

Content Type: application/json;charset=utf-8
{
    "comments": [{
        "content": "Projects",
        "id": 57000001124005,
        "created_time_long": 1408625664048,
        "added_by": "2060758",
        "added_person": "Boyle Patricia",
        "created_time_format": "08-20-2014 09:54 PM",
        "created_time": "08-20-2014"
    }, {
        "content": "Check with Sales team",
        "id": 57000001153001,
        "created_time_long": 1411755818829,
        "added_by": "2060758",
        "added_person": "Boyle Patricia",
        "created_time_format": "09-26-2014 03:23 AM",
        "created_time": "09-26-2014"
    }]
}

 Add Comment

Adds a task comment.

POST  /portal/[PORTALID]/projects/[PROJECTID]/tasks/[TASKID]/comments/

Scope: ZohoProjects.tasks.CREATE

Request Parameters

content*String Comment for the task.

Sample Response

Status: 201 Created

Content Type: application/json;charset=utf-8
{
    "comments": [{
        "content": "Setup Demo Video",
        "id": 57000001149011,
        "created_time_long": 1411756962722,
        "added_by": "2060758",
        "added_person": "Boyle Patricia",
        "created_time_format": "09-26-2014 03:42 AM",
        "created_time": "09-26-2014"
    }]
}

 Update Comment

Updates the description of task comment.

GET  POST /portal/[PORTALID]/projects/[PROJECTID]/tasks/[TASKID]/comments/[COMMENTID]/

Scope: ZohoProjects.tasks.UPDATE

Request Parameters

content*StringComment for the task.

Sample Response

Status: 200 Success

Content Type: application/json;charset=utf-8
{
    "comments": [{
        "content": "Setup Demo Video",
        "id": 57000001149011,
        "created_time_long": 1411756962722,
        "added_by": "2060758",
        "added_person": "Boyle Patricia",
        "created_time_format": "09-26-2014 03:42 AM",
        "created_time": "09-26-2014"
    }]
}

 Delete Comment

Deletes the task comment.

DELETE /portal/[PORTALID]/projects/[PROJECTID]/tasks/[TASKID]/comments/[COMMENTID]/

Scope: ZohoProjects.tasks.DELETE

Sample Response

Status: 200 Success

Content Type: application/json;charset=utf-8
{
    "response": "Comment Deleted Successfully"
}

 Get Task Attachments

Retrieve details of attachments associated to the task.

GET /portal/[PORTALID]/projects/[PROJECTID]/tasks/[TASKID]/attachments/

Scope: ZohoProjects.tasks.READ

Sample Response

Status: 200 Success

Content Type: application/json;charset=utf-8
[{
    "CONTENT_TYPE": "pdf",
    "AUTHOR_ID": "565296969",
    "THUMBNAIL_URL": "https://download.zoho.com/paramdownloadservlet?x-service=EX&x-encoding=gzip&x-mode=2&x-resource_id=033zqca7d98669ef541348a5d2ded5d44ff3d&event-id=033zqca7d98669ef541348a5d2ded5d44ff3d_350x262&x-w=350&x-h=262",
    "FILENAME": "mybook.pdf",
    "UPLOADED_TIME": 1476939840136,
    "DOWNLOAD_URL": "https://download.zoho.com/paramdownloadservlet?x-service=EX&event-id=033zqca7d98669ef541348a5d2ded5d44ff3d_1476939885220&x-encoding=gzip&x-resource_id=033zqca7d98669ef541348a5d2ded5d44ff3d",
    "RESOURCE_ID": "033zqca7d98669ef541348a5d2ded5d44ff3d",
    "OWNER": "Boyle Patricia"
}]

 Delete Task Attachments

Delete attachments associated with the task.

DELETE /portal/[PORTALID]/projects/[PROJECTID]/tasks/[TASKID]/attachments/[ATTACHMENTID]/

Scope: ZohoProjects.tasks.DELETE

Sample Response

Status: 200 Success

Content Type: application/json;charset=utf-8
{
     "response": "Task Document Deleted Successfully"
}

Get All Task Layouts

View the list of all the task layouts available in your portal.

GET  /portal/[PORTALID]/tasklayouts

Scope: ZohoProjects.projects.READ

Sample Response

Status: 200 Success

Content Type: application/json;charset=utf-8
{
    "layouts": [{
        "layout_name": "CustomizedLayout",
        "layout_id": "932200000000304001",
        "is_default": false
    }, {
        "layout_name": "Standard Layout",
        "layout_id": "932200000000277011",
        "is_default": true
    }]
}
    }]
}

Get Task Layout Details

Fetch the details of a task layout as necessary.

GET  /portal/[PORTALID]/projects/[PROJECTID]/tasklayouts

Scope: ZohoProjects.projects.READ

Sample Response

Status: 200 Success

Content Type: application/json;charset=utf-8
{
    "layout_id": "932200000000304001",
    "section_details": [{
        "section_name": "Task Information",
        "customfield_details": [{
            "column_name": "LOGINNAME",
            "is_mandatory": false,
            "is_default": true,
            "display_name": "Owner",
            "column_type": "userpicklist"
        }, {
            "column_name": "CUSTOM_STATUSID",
            "is_mandatory": false,
            "is_default": true,
            "display_name": "Status",
            "column_type": "picklist"
        }, {
            "column_name": "PRIORITY",
            "is_mandatory": false,
            "is_default": true,
            "display_name": "Priority",
            "column_type": "picklist"
        }, {
            "column_name": "PERCENTCOMPLETE",
            "is_mandatory": false,
            "is_default": true,
            "display_name": "Percentcomplete",
            "column_type": "singleline"
        }],
        "is_default": false
    }, {
        "section_name": "New Section",
        "customfield_details": [{
            "column_name": "UDF_CHAR1",
            "is_mandatory": false,
            "is_default": false,
            "display_name": "My_Field",
            "column_type": "singleline"
        }, {
            "column_name": "UDF_DATE1",
            "is_mandatory": false,
            "is_default": false,
            "display_name": "My_Date",
            "column_type": "date"
        }],
        "is_default": false
    }],
    "status_details": [{
        "is_start": true,
        "color": "#eb5768",
        "name": "Open",
        "id": "932200000000277068",
        "is_default": true,
        "type": "open"
    }, {
        "is_start": false,
        "color": "#8eb15a",
        "name": "Closed",
        "id": "932200000000277071",
        "is_default": true,
        "type": "closed"
    }, {
        "is_start": false,
        "color": "#935b1a",
        "name": "To be Tested",
        "id": "932200000000345019",
        "is_default": false,
        "type": "open"
    }]
}
    }]
}

Share this post : FacebookTwitter

Still can't find what you're looking for?

Write to us: support@zohoprojects.com