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.
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.
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.
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.
Scope: ZohoProjects.portals.READ
Sample Response
Get Project Custom Fields
Gets all the project custom fields.
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.
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.
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.
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
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 | 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
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 | 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
Scope: ZohoProjects.projects.DELETE
Sample Response
Status: 200 Success Content Type: application/json;charset=utf-8
{
"response": "Project Deleted Successfully"
}