Project Manager System | Projects API :Zoho Projects

Projects API

Scope: ZohoProjects.projects.{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 Projects
GET /restapi/portal/[PORTALID]/projects/

Project Details
GET /restapi/portal/[PORTALID]/projects/[PROJECTID]/

Get Project Layouts
Get /restapi/portal/[PORTALID]/module/projects/layouts/

Get Layout Details
Get /restapi/portal/[PORTALID]/module/projects/layouts/[LAYOUTID]/

Get Project Custom Fields
Get /restapi/portal/[PORTALID]/projects/customfields/

Get Project Custom Status
Get /restapi/portal/[PORTALID]/module/projects/customfields/

Get Project Groups
Get /restapi/portal/[PORTALID]/projects/groups/

Create a Project Group
POST /restapi/portal/[PORTALID]/projectgroups/

Create a Project
POST /restapi/portal/[PORTALID]/projects/

Update a Project
POST /restapi/portal/[PORTALID]/projects/[PROJECTID]/

Delete a Project
DELETE /restapi/portal/[PORTALID]/projects/[PROJECTID]/

All Projects

Get all the projects in the portal for the logged in user.

GET /restapi/portal/[PORTALID]/projects/

Scope: ZohoProjects.projects.READ

Request Parameters

index	int	Index number of the project.
range	int	Range of the projects.
status	String	Status of the project must be active or archived or template
sort_column	String	Sort projects using the last modified time or time of creation. (created_time / last_modified_time)
sort_order	String	Sort in ascending / descending order
last_modified_time	Long	Last updated time of the project in millis.
reverse_order	Boolean	Specify true to sort the projects in reverse order. Accepted values: true and false.
json_string	json object	Filter projects based on groups and assignee. Specify the group ID values(Long) in group and user ID values(Long) in assignee. Ex. { "filter" : {"group" : ["4000000026067","0"] , "assignee" : ["5629101","5629231"] } } "0" is specified in group to filter ungrouped projects.

Status: 200 Success

Content Type: application/json;charset=utf-8

{
  "projects": [
    {
      "end_date": "04-25-2019",
      "is_strict": "no",
      "project_percent": "0",
      "role": "admin",
      "bug_count": {
        "closed": 0,
        "open": 0
      },
      "IS_BUG_ENABLED": true,
      "budget_value": "0",
      "owner_id": "639283127",
      "taskbug_prefix": "BM1",
      "link": {
        "activity": {
        "url": "https://projectsapi.zoho.com/restapi/portal/2063927/projects/170876000006477013/activities/"
        },
        "document": {
        "url": "https://projectsapi.zoho.com/restapi/portal/2063927/projects/170876000006477013/documents/"
        },
        "forum": {
        "url": "https://projectsapi.zoho.com/restapi/portal/2063927/projects/170876000006477013/forums/"
        }
},
     "custom_status_id": "170876000005348089",
      "milestone_count": {
        "closed": 0,
        "open": 0
      },
      "start_date_long": 1554057000000,
      "updated_date_long": 1556187579443,
      "show_project_overview": false,
      "end_date_long": 1556216999000,
      "task_count": {
        "closed": 0,
        "open": 0
      },
],
"name": "Billing Method",
      "is_public": "no",
      "id_string": "170876000006477013",
      "created_date": "04-25-2019",
      "updated_date": "04-25-2019",
      "bug_prefix": "BM1-I",
      "cascade_setting": {
        "date": false,
        "logHours": false,
        "plan": true,
        "percentage": false,
        "workHours": false
      },
"name": "Website Version 2",
      "is_public": "no",
      "id_string": "170876000001789005",
      "created_date": "04-23-2014",
      "updated_date": "02-26-2019",
      "bug_prefix": "WV2",
      "cascade_setting": {
        "date": false,
        "logHours": false,
        "plan": false,
        "percentage": false,
        "workHours": false
      },
      "layout_details": {
        "task": {
          "name": "Standard Layout",
          "id": "170876000004668011"
        },
        "project": {
          "name": "zp.customfields.defaultlayout",
          "id": "170876000005348008"
        }
      },
      "status": "active"
    }
  ]
}

Project Details

Lists all the details of the project.

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

Scope: ZohoProjects.projects.READ

Sample Response

Status: 200 Success

Content Type: application/json;charset=utf-8

{
  "projects": [
    {
      "is_strict": "no",
      "project_percent": "0",
      "role": "admin",
      "bug_count": {
        "closed": 0,
        "open": 0
      },
      "IS_BUG_ENABLED": true,
      "budget_value": "250",
      "owner_id": "639283127",
      "taskbug_prefix": "ZS1",
      "link": {
        "activity": {
       "url": "https://projectsapi.zoho.com/restapi/portal/2063927/projects/170876000006377005/activities/"
        },
        "document": {
       "url": "https://projectsapi.zoho.com/restapi/portal/2063927/projects/170876000006377005/documents/"
        },
        "forum": {
          "url": "https://projectsapi.zoho.com/restapi/portal/2063927/projects/170876000006377005/forums/"
        },
        "timesheet": {
          "url": "https://projectsapi.zoho.com/restapi/portal/2063927/projects/170876000006377005/logs/"
        },
        "task": {
          "url": "https://projectsapi.zoho.com/restapi/portal/2063927/projects/170876000006377005/tasks/"
        },
"start_date_long": 1570645800000,
      "threshold": "100.000",
      "updated_date_long": 1560335374305,
      "show_project_overview": false,
      "task_count": {
        "closed": 0,
        "open": 4
      },
 "layout_details": {
        "task": {
          "name": "Standard Layout",
          "id": "170876000004668011"
        },
        "project": {
          "name": "zp.customfields.defaultlayout",
          "id": "170876000005348008"
        }
      },
      "status": "active"
    }
  ]
}

Get Project Layouts

Gets list of project layouts.

GET /restapi/portal/[PORTALID]/module/projects/layouts/

Scope: ZohoProjects.portals.READ

Sample Response

Status: 200 Success

Content Type: application/json;charset=utf-8

{
  "layout":[
    {
      "layout_id":"22262000000498001",
      "layout_name":"BluePrint","is_default":false
    },
    {
      "layout_id":"22262000000489001",
      "layout_name":"from standard","is_default":false
    },
    {
      "layout_id":"22262000000468001",
      "layout_name":"new to be tested","is_default":false
    },
    {
      "layout_id":"22262000000465189",
      "layout_name":"new in 7.0","is_default":false
    },
    {
      "layout_id":"22262000000440001",
      "layout_name":"new layout","is_default":false
    },
    {
      "layout_id":"22262000000397006",
      "layout_name":"zp.customfields.defaultlayout","is_default":true
    }
    ]
}

Get Layout Details

Gets layout details.

GET /restapi/portal/[PORTALID]/module/projects/layouts/[LAYOUTID]/

Scope: ZohoProjects.portals.READ

Sample Response

Get Project Custom Fields

Gets all the project custom fields.

GET /restapi/portal/[PORTALID]/projects/customfields/

Scope: ZohoProjects.projects.READ

Note:

To create projects with custom fields, you need to pass the value received for the field_id in this response. The value that you receive here becomes the param in the Create a Project API.

Sample Response

Status: 200 Success

Content Type: application/json;charset=utf-8

{
  "project_custom_fields": [
    {
      "field_id": "UDF_CHAR1",
      "is_visible": true,
      "is_pii": false,
      "is_encrypted": false,
      "default_value": "1",
      "id": "5000000035009",
      "field_type": "single_line",
      "field_name": "Description:"
    }
  ]
}

Get Project Custom Status

Gets list of all project custom status.

GET /restapi/portal/[PORTALID]/module/projects/status/

Scope: ZohoProjects.portals.READ

Sample Response

Status: 200 Success

Content Type: application/json;charset=utf-8

{
  "project_custom_status": [
    {
      "status_id":"22262000000397087",
      "status_name":"zp.projstatus.active",
      "status_color":"statuscol_nocolor",
      "status_color_hexcode":"#ffffff",
      "is_closed":false,
      "is_default_value":false,
      "is_default":false,"sequence":0
    },
    {
      "status_id": "22262000000397090",
      "status_name": "zp.projstatus.inprogress",
      "status_color": "statuscol_blue",
      "status_color_hexcode": "#08aeea",
      "is_closed": false,
      "is_default_value": false,
      "is_default": false,
      "sequence": 0
    },
    {
      "status_id": "22262000000397093",
      "status_name": "zp.projstatus.ontrack",
      "status_color": "statuscol_green",
      "status_color_hexcode": "#74cb80",
      "is_closed": false,
      "is_default_value": false,
      "is_default": false,
      "sequence": 0
    }
  ]
}

Get Project Groups

Gets all the project groups.

GET /restapi/portal/[PORTALID]/projects/groups

Scope:ZohoProjects.projects.READ

Request Parameters

index	int	Index number of the project.
range	int	Range of the projects.

Sample Response

Status: 200 Success

Content Type: application/json;charset=utf-8

{
  "groups": [
    {
      "name": "Marketing",
      "id": "4000000026055"
    },
    {
      "name": "Designing",
      "id": "4000000026059"
    },
    {
      "name": "Public Relations",
      "id": "4000000033001"
    }
  ]
}

Create a Project Group

Creates a project group in the portal.

POST /restapi/portal/[PORTALID]/projectgroups/

Scope:ZohoProjects.projects.CREATE

Request Parameters

name

string

Name of the Project Group

Sample response

Status: 201 Created

Content Type: application/json;charset=utf-8

{
"groups": [
{
"name": "group 1",
"id": "40200000001967015"
}
]
}

Create a Project

POST /restapi/portal/[PORTALID]/projects/

Scope: ZohoProjects.projects.CREATE

Request Parameters

name*	String [100]	Name of the project.
owner	Long	Zoho user ID. If this param is not set, the user who creates the project will be mapped as the owner by default.
description	String	Description of the project.
template_id	Long	Template ID of the project.
start_date	String [MM-DD-YYYY]	Start date of the project.
end_date	String [MM-DD-YYYY]	End date of the project.
strict_project	String	The value for strict projects must be either 1 or 2. (1 = Not strict, 2 = Strict)
<field_id> ex: UDF_CHAR1 UDF_MULTI1 UDF_MULTIUSER1	String	The value of the custom field. UDF_MULTI1 is a multi-value pick list parameter. To add values, say value1, value2 and value3, the parameters has to be passed as UDF_MULTI1=value1&UDF_MULTI1=value2&UDF_MULTI1=value3. UDF_MULTIUSER1 is a multi-user pick list parameter. To add users, say user1, user2 and user3, the parameters has to be passed as UDF_MULTIUSER1=userid1&UDF_MULTIUSER1=userid2&UDF_MULTIUSER1=userid3.
budget_type	int	Enter the Budget type. Accepted values 0, 1, 3, 5 and 7. (0 = None, 1 = Based on Project, 3 = Based on Milestone, 5 = Based on Task and 7 = Based on User)
budget_value	Float	Specify the Cost Budget or Budgeted Hours based on the selected budget type.
budget_tracking_method	int	Method to track your project budget. Accepted values 1, 2, and 4. (1 = Project hours, 2 = Staff hours, 4 = Task / Issue hours)
threshold	Float	Enter the Budgeted Hours Threshold or Cost Budget Threshold.
currency	String	The default currency of your project. Example: USD, INR, etc.
project_rate	Float	Specify the rate per hour of your project.
fixed_cost	Float	Fixed cost for your project.
billing_method	int	Mention the billing method for invoicing. Accepted values 1, 2, 3 and 4. (1 = Based on project hours, 2 = Based on staff hours, 3 = Fixed cost for project, 4 = Based on task / issue hours)
group_id	Long	Specify the Group ID.
bill_status	String	Acceptable values: Billable and Non billable.
enable_rollup	Boolean	Accepted values: yes or no.
public	Boolean	Accepted values: yes or no.
cost_per_hour	float	Specify the project's Cost per hour.
revenue_budget	float	Specify the Revenue Budget.
enable_sprints	string	Accepted values: yes or no.

Note:

The project custom field feature is available only in the Enterprise plan. The params that you need to pass for the project custom fields is the value in <field_id> in Get Project Custom Fields API.
Strict project feature is available only for paid plans.

Example of creating a project with custom fields

Since custom field names are not unique, custom fields are referred by their respective < field_id>. The same custom field name will be referred with different field Ids.

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

Here is a sample response of a custom field:

{
"project_custom_fields": [{
"is_visible": false,
"field_name": "Supported browser",
"field_type": "single_line",
"default_value": "Chrome",
"field_id": "UDF_CHAR1"
}]
}

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

Firefox is the value for the "Supported browser" field.

Notice that the name of the field Supported browser" will not be used anywhere while creating projects.

Sample Response

Status: 201 Created

Content Type: application/json;charset=utf-8

  {
    "projects": [{
        "id": 170876000001849005,
        "task_count": {
            "open": 0,
            "closed": 0
        },
        "milestone_count": {
            "open": 0,
            "closed": 0
        },
        "bug_count": {
            "open": 0,
            "closed": 0
        },
        "name": "SAP Projects",
        "status": "active",
        "created_date": "05-26-2014 10:34 AM",
        "created_date_long": 1401109494737,
        "description": "This project is used to implement end to end SAP for large scale companies.",
        "owner_name": "Patricia Boyle",
        "owner_id": "2060758",
        "link": {
            "self": {
                "url": "https://projectsapi.zoho.com/restapi/portal/
                        2063927/projects/170876000001849005/"
            },
            "activity": {
                "url": "https://projectsapi.zoho.com/restapi/portal/
                        2063927/projects/170876000001849005/activities/"
            },
            "status": {
                "url": "https://projectsapi.zoho.com/restapi/portal/
                        2063927/projects/170876000001849005/statuses/"
            },
            "milestone": {
                "url": "https://projectsapi.zoho.com/restapi/portal/
                        2063927/projects/170876000001849005/milestones/"
            },
            "tasklist": {
                "url": "https://projectsapi.zoho.com/restapi/portal/
                        2063927/projects/170876000001849005/tasklists/"
            },
            "task": {
                "url": "https://projectsapi.zoho.com/restapi/portal/
                        2063927/projects/170876000001849005/tasks/"
            },
            "bug": {
                "url": "https://projectsapi.zoho.com/restapi/portal/
                        2063927/projects/170876000001849005/bugs/"
            },
            "timesheet": {
                "url": "https://projectsapi.zoho.com/restapi/portal/
                        2063927/projects/170876000001849005/logs/"
            },
            "event": {
                "url": "https://projectsapi.zoho.com/restapi/portal/
                        2063927/projects/170876000001849005/events/"
            },
            "document": {
                "url": "https://projectsapi.zoho.com/restapi/portal/
                        2063927/projects/170876000001849005/documents/"
            },
            "folder": {
                "url": "https://projectsapi.zoho.com/restapi/portal/
                        2063927/projects/170876000001849005/folders/"
            },
            "forum": {
                "url": "https://projectsapi.zoho.com/restapi/portal/
                        2063927/projects/170876000001849005/forums/"
            },
            "user": {
                "url": "https://projectsapi.zoho.com/restapi/portal/
                        2063927/projects/170876000001849005/users/"
            }
        }
    }]
}

Update a Project

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

Scope: ZohoProjects.projects.UPDATE

Request Parameters

name	String [100]	Name of the project.
owner	Long	User ID.
description	String	Description of the project.
status	String	Status of the project must be active or archived.
custom_status	Long	Custom status ID
start_date	String [MM-DD-YYYY]	Start date of the project.
end_date	String [MM-DD-YYYY]	End date of the project.
strict_project	String	The value for strict projects must be either 1 or 2. (1 = Not strict, 2 = Strict)
<field_id> ex: UDF_CHAR1 UDF_MULTI1 UDF_MULTIUSER1	String	The value of the custom field. UDF_MULTI1 is a multi-value pick list parameter. To update values, say value1, value2 and value3, the parameters has to be passed as UDF_MULTI1=value1&UDF_MULTI1=value2&UDF_MULTI1=value3. UDF_MULTIUSER1 is a multi-user pick list parameter. To update users, say user1, user2 and user3, the parameters has to be passed as UDF_MULTIUSER1=userid1&UDF_MULTIUSER1=userid2&UDF_MULTIUSER1=userid3.
budget_type	int	Enter the Budget type. Accepted values 0, 1, 3, 5 and 7. (0 = None, 1 = Based on Project, 3 = Based on Milestone, 5 = Based on Task and 7 = Based on User)
budget_value	Float	Specify the Cost Budget or Budgeted Hours based on the selected budget type.
threshold	Float	Enter the Budgeted Hours Threshold or Cost Budget Threshold.
currency	String	The default currency of your project. Example: USD, INR, etc.
project_rate	Float	Specify the rate per hour of your project.
fixed_cost	Float	Fixed cost for your project.
billing_method	int	Enter the billing method for invoicing. Accepted values 1, 2, 3 and 4. (1 = Based on project hours, 2 = Based on staff hours, 3 = Fixed cost for project, 4 = Based on task / issue hours)
group_id	Long	Specify the Group ID.
enable_rollup	Boolean	Accepted values: yes or no.
cost_per_hour	float	Specify the project's Cost per hour.
revenue_budget	float	Specify the Revenue Budget.

Example of updating a project with custom fields

Since custom field names are not unique, custom fields are referred by their respective < field_id>. The same custom field name will be referred with different field Ids.

You must first get all the custom fields, and then pass the <field_id> value of the custom field as a param to update your project with the custom fields.

Here is a sample response of a custom field:

{
"project_custom_fields": [{
"is_visible": false,
"field_name": "Supported browser",
"field_type": "single_line",
"default_value": "Firefox",
"field_id": "UDF_CHAR1"
}]
}

UDF_CHAR1 is the param that you need to pass while updating projects.

Chrome is the value for the "Supported browser" field.

Notice that the name of the field Supported browser" will not be used anywhere while updating projects.

Sample Response

Status: 200 Success

Content Type: application/json;charset=utf-8

{
    "projects": [{
        "id": 170876000001849005,
        "task_count": {
            "open": 22,
            "closed": 11
        },
        "milestone_count": {
            "open": 15,
            "closed": 7
        },
        "bug_count": {
            "open": 18,
            "closed": 8
        },
        "name": "SAP Projects",
        "status": "archived",
        "created_date": "05-26-2014 10:34 AM",
        "created_date_long": 1401109494737,
        "description": "The project has been successfully implemented in 100 companies.",
        "owner_name": "Patricia Boyle",
        "owner_id": "2060758",
        "link": {
            "self": {
                "url": "https://projectsapi.zoho.com/restapi/portal/
                        2063927/projects/170876000001849005/"
            },
            "activity": {
                "url": "https://projectsapi.zoho.com/restapi/portal/
                        2063927/projects/170876000001849005/activities/"
            },
            "status": {
                "url": "https://projectsapi.zoho.com/restapi/portal/
                        2063927/projects/170876000001849005/statuses/"
            },
            "milestone": {
                "url": "https://projectsapi.zoho.com/restapi/portal/
                        2063927/projects/170876000001849005/milestones/"
            },
            "tasklist": {
                "url": "https://projectsapi.zoho.com/restapi/portal/
                        2063927/projects/170876000001849005/tasklists/"
            },
            "task": {
                "url": "https://projectsapi.zoho.com/restapi/portal/
                        2063927/projects/170876000001849005/tasks/"
            },
            "bug": {
                "url": "https://projectsapi.zoho.com/restapi/portal/
                        2063927/projects/170876000001849005/bugs/"
            },
            "timesheet": {
                "url": "https://projectsapi.zoho.com/restapi/portal/
                        2063927/projects/170876000001849005/logs/"
            },
            "event": {
                "url": "https://projectsapi.zoho.com/restapi/portal/
                        2063927/projects/170876000001849005/events/"
            },
            "document": {
                "url": "https://projectsapi.zoho.com/restapi/portal/
                        2063927/projects/170876000001849005/documents/"
            },
            "folder": {
                "url": "https://projectsapi.zoho.com/restapi/portal/
                        2063927/projects/170876000001849005/folders/"
            },
            "forum": {
                "url": "https://projectsapi.zoho.com/restapi/portal/
                        2063927/projects/170876000001849005/forums/"
            },
            "user": {
                "url": "https://projectsapi.zoho.com/restapi/portal/
                        2063927/projects/170876000001849005/users/"
            }
        }
    }]
}

Delete a Project

DELETE /restapi/portal/[PORTALID]/projects/[PROJECTID]/

Scope: ZohoProjects.projects.DELETE

Sample Response

Status: 200 Success

Content Type: application/json;charset=utf-8

{
    "response": "Project Deleted Successfully"
}