API Docs
/
No Results Found
Projects

Projects

A project is a series of tasks performed over a period of time, to achieve certain targets. There can be many number of people working on a single project and a project may consist of single or multiple tasks. A project is billed and charged upon a customer whom the project was taken up for.

Attribute

project_id
string
project_name
string
Name of the project. Max-length [100]
customer_id
string
Search projects by customer id.
customer_name
string
currency_code
string
description
string
status
string
billing_type
string
The way you bill your customer. Allowed Values: fixed_cost_for_project, based_on_project_hours, based_on_staff_hours and based_on_task_hours
rate
float
budget_type
string
total_hours
string
total_amount
double
billed_hours
string
billed_amount
double
un_billed_hours
string
un_billed_amount
double
billable_hours
string
billable_amount
double
non_billable_hours
string
non_billable_amount
double
cost_budget_amount
double
Budgeted Cost to complete this project
is_recurrence_associated
boolean
recurring_invoices
array
created_time
string
show_in_dashboard
boolean
tasks
array
Show Sub-Attributes arrow
task_id
string
task_name
string
description
string
rate
float
budget_hours
string
Task budget hours.
total_hours
string
billed_hours
string
un_billed_hours
string
non_billable_hours
string
status
string
is_billable
boolean
task_custom_fields
string
users
array
Show Sub-Attributes arrow
user_id
string
ID of the user to be added to the project.
is_current_user
boolean
user_name
string
Name of the user. Max-length [200]
email
string
Email of the user. Max-length [100]
user_role
string
Role to be assigned. Allowed Values: staff, admin and timesheetstaff
status
string
rate
float
budget_hours
string
Task budget hours.
total_hours
string
billed_hours
string
un_billed_hours
string
cost_rate
double

Example

{ "project_id": "460000000044019", "project_name": "REAL TIME TRAFFIC FLUX", "customer_id": "460000000044001", "customer_name": "SAF Instruments Inc", "currency_code": "USD", "description": "A simple algorithm is to be tested with vehicle detection application.", "status": "active", "billing_type": "fixed_cost_for_project", "rate": 5000, "budget_type": " ", "total_hours": "12:26", "total_amount": 500, "billed_hours": "12:27", "billed_amount": 500, "un_billed_hours": "00:00", "un_billed_amount": 0, "billable_hours": "12:26", "billable_amount": 500, "non_billable_hours": "0.00", "non_billable_amount": 0, "cost_budget_amount": "1000.00", "is_recurrence_associated": false, "recurring_invoices": [ "string" ], "created_time": "2013-09-18T18:05:27+0530", "show_in_dashboard": true, "tasks": [ { "task_id": "460000000044009", "task_name": "Distribution Analysis", "description": "A simple algorithm is to be tested with vehicle detection application.", "rate": 5000, "budget_hours": "0", "total_hours": "12:26", "billed_hours": "12:27", "un_billed_hours": "00:00", "non_billable_hours": "0.00", "status": "active", "is_billable": true, "task_custom_fields": "" } ], "users": [ { "user_id": "460000000024003", "is_current_user": true, "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "status": "active", "rate": 5000, "budget_hours": "0", "total_hours": "12:26", "billed_hours": "12:27", "un_billed_hours": "00:00", "cost_rate": "10.00" } ] }

Create a project

Create a project.
oauthscope : ZohoBooks.projects.CREATE

Arguments

project_name
string
(Required)
Name of the project. Max-length [100]
customer_id
string
(Required)
ID of the customer.
description
string
Project description. Max-length [500]
billing_type
string
(Required)
The way you bill your customer. Allowed Values: fixed_cost_for_project, based_on_project_hours, based_on_staff_hours and based_on_task_hours
rate
string
Hourly rate for a task.
budget_type
string
The way you budget. Allowed Values: total_project_cost, total_project_hours, hours_per_task and hours_per_staff
budget_hours
string
Task budget hours
budget_amount
string
Give value, if you are estimating total project revenue budget.
cost_budget_amount
double
Budgeted Cost to complete this project
user_id
string
(Required)
ID of the user to be added to the project.
tasks
array
Show Sub-Attributes arrow
task_name
string
(Required)
Name of the task. Max-length [100]
description
string
Task description. Max-length [500]
rate
string
Hourly rate of a task.
budget_hours
string
Task budgeting.
users
array
Show Sub-Attributes arrow
user_id
string
(Required)
ID of the user to be added to the project.
is_current_user
boolean
user_name
string
Name of the user. Max-length [200]
email
string
Email of the user. Max-length [100]
user_role
string
Role to be assigned. Allowed Values: staff, admin and timesheetstaff
status
string
rate
string
Hourly rate for a task.
budget_hours
string
Task budget hours
total_hours
string
billed_hours
string
un_billed_hours
string
cost_rate
double

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/projects -X POST -d '{"field":"value","field":"value"}'

Body Parameters

Click to copy
{ "project_name": "Network Distribution", "customer_id": "460000000044001", "description": "Distribution for the system of intermediaries between the producer of goods and/or services and the final user", "billing_type": "based_on_task_hours", "rate": " ", "budget_type": " ", "budget_hours": " ", "budget_amount": " ", "cost_budget_amount": "1000.00", "user_id": "INV-00003", "tasks": [ { "task_name": "INV-00003", "description": "INV-00003", "rate": "INV-00003", "budget_hours": "INV-00003" } ], "users": [ { "user_id": "INV-00003", "is_current_user": true, "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "status": "active", "rate": " ", "budget_hours": " ", "total_hours": "12:26", "billed_hours": "12:27", "un_billed_hours": "00:00", "cost_rate": "10.00" } ] }

Response Example

{ "code": 0, "message": "The project has been created.", "project": { "project_id": "460000000044019", "project_name": "REAL TIME TRAFFIC FLUX", "customer_id": "460000000044001", "customer_name": "SAF Instruments Inc", "currency_code": "USD", "description": "A simple algorithm is to be tested with vehicle detection application.", "status": "active", "billing_type": "fixed_cost_for_project", "rate": 5000, "budget_type": " ", "total_hours": "12:26", "total_amount": 500, "billed_hours": "12:27", "billed_amount": 500, "un_billed_hours": "00:00", "un_billed_amount": 0, "billable_hours": "12:26", "billable_amount": 500, "non_billable_hours": "0.00", "non_billable_amount": 0, "cost_budget_amount": "1000.00", "is_recurrence_associated": false, "recurring_invoices": [ "string" ], "created_time": "2013-09-18T18:05:27+0530", "show_in_dashboard": true, "tasks": [ { "task_id": "460000000044009", "task_name": "Distribution Analysis", "description": "A simple algorithm is to be tested with vehicle detection application.", "rate": 5000, "budget_hours": "0", "total_hours": "12:26", "billed_hours": "12:27", "un_billed_hours": "00:00", "non_billable_hours": "0.00", "status": "active", "is_billable": true, "task_custom_fields": "" } ], "users": [ { "user_id": "460000000024003", "is_current_user": true, "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "status": "active", "rate": 5000, "budget_hours": "0", "total_hours": "12:26", "billed_hours": "12:27", "un_billed_hours": "00:00", "cost_rate": "10.00" } ] } }

List projects

List all projects with pagination.
oauthscope : ZohoBooks.projects.READ

Query Parameters

filter_by
Filter projects by any status. Allowed Values: Status.All, Status.Active and Status.Inactive
customer_id
Search projects by customer id.
sort_column
Sort projects. Allowed Values: project_name, customer_name, rate and created_time

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/projects -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "code": 0, "message": "success", "projects": [ { "project_id": "460000000044019", "project_name": "REAL TIME TRAFFIC FLUX", "customer_id": "460000000044001", "customer_name": "SAF Instruments Inc", "description": "A simple algorithm is to be tested with vehicle detection application.", "status": "active", "billing_type": "fixed_cost_for_project", "rate": 5000, "created_time": "2013-09-18T18:05:27+0530", "has_attachment": false, "total_hours": "12:26", "billable_hours": "12:26" }, {...}, {...} ], "page_context": [ { "page": 10, "per_page": 450, "report_name": "Projects", "has_more_page": false, "sort_order": "D", "sort_column": "created_time" } ] }

Update project

Update details of a project.
oauthscope : ZohoBooks.projects.UPDATE

Arguments

project_name
string
(Required)
Name of the project. Max-length [100]
customer_id
string
(Required)
ID of the customer.
description
string
Project description. Max-length [500]
billing_type
string
(Required)
The way you bill your customer. Allowed Values: fixed_cost_for_project, based_on_project_hours, based_on_staff_hours and based_on_task_hours
rate
string
Hourly rate for a task.
budget_type
string
The way you budget. Allowed Values: total_project_cost, total_project_hours, hours_per_task and hours_per_staff
budget_hours
string
Task budget hours
budget_amount
string
Give value, if you are estimating total project revenue.
cost_budget_amount
double
Budgeted Cost to complete this project
user_id
string
(Required)
ID of the user to be added to the project.
tasks
array
Show Sub-Attributes arrow
task_name
string
(Required)
Name of the task. Max-length [100]
description
string
Task description. Max-length [500]
rate
string
Hourly rate of a task.
budget_hours
string
Task budgeting.
users
array
Show Sub-Attributes arrow
user_id
string
(Required)
ID of the user to be added to the project.
is_current_user
boolean
user_name
string
Name of the user. Max-length [200]
email
string
Email of the user. Max-length [100]
user_role
string
Role to be assigned. Allowed Values: staff, admin and timesheetstaff
status
string
rate
string
Hourly rate for a task.
budget_hours
string
Task budget hours
total_hours
string
billed_hours
string
un_billed_hours
string
cost_rate
double

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/projects/{project_id} -X PUT -d '{"field":"value","field":"value"}'

Body Parameters

Click to copy
{ "project_name": "Network Distribution", "customer_id": "460000000044001", "description": "Distribution for the system of intermediaries between the producer of goods and/or services and the final user", "billing_type": "based_on_task_hours", "rate": " ", "budget_type": " ", "budget_hours": " ", "budget_amount": " ", "cost_budget_amount": "1000.00", "user_id": "INV-00003", "tasks": [ { "task_name": "INV-00003", "description": "INV-00003", "rate": "INV-00003", "budget_hours": "INV-00003" } ], "users": [ { "user_id": "INV-00003", "is_current_user": true, "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "status": "active", "rate": " ", "budget_hours": " ", "total_hours": "12:26", "billed_hours": "12:27", "un_billed_hours": "00:00", "cost_rate": "10.00" } ] }

Response Example

{ "code": 0, "message": "The project information has been updated.", "project": { "project_id": "460000000044019", "project_name": "REAL TIME TRAFFIC FLUX", "customer_id": "460000000044001", "customer_name": "SAF Instruments Inc", "currency_code": "USD", "description": "A simple algorithm is to be tested with vehicle detection application.", "status": "active", "billing_type": "fixed_cost_for_project", "rate": 5000, "budget_type": " ", "total_hours": "12:26", "total_amount": 500, "billed_hours": "12:27", "billed_amount": 500, "un_billed_hours": "00:00", "un_billed_amount": 0, "billable_hours": "12:26", "billable_amount": 500, "non_billable_hours": "0.00", "non_billable_amount": 0, "cost_budget_amount": "1000.00", "is_recurrence_associated": false, "recurring_invoices": [ "string" ], "created_time": "2013-09-18T18:05:27+0530", "show_in_dashboard": true, "tasks": [ { "task_id": "460000000044009", "task_name": "Distribution Analysis", "description": "A simple algorithm is to be tested with vehicle detection application.", "rate": 5000, "budget_hours": "0", "total_hours": "12:26", "billed_hours": "12:27", "un_billed_hours": "00:00", "non_billable_hours": "0.00", "status": "active", "is_billable": true, "task_custom_fields": "" } ], "users": [ { "user_id": "460000000024003", "is_current_user": true, "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "status": "active", "rate": 5000, "budget_hours": "0", "total_hours": "12:26", "billed_hours": "12:27", "un_billed_hours": "00:00", "cost_rate": "10.00" } ] } }

Get a project

Get the details of a project.
oauthscope : ZohoBooks.projects.READ

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/projects/{project_id}

Response Example

{ "code": 0, "message": "success", "project": { "project_id": "460000000044019", "project_name": "REAL TIME TRAFFIC FLUX", "customer_id": "460000000044001", "customer_name": "SAF Instruments Inc", "currency_code": "USD", "description": "A simple algorithm is to be tested with vehicle detection application.", "status": "active", "billing_type": "fixed_cost_for_project", "rate": 5000, "budget_type": " ", "total_hours": "12:26", "total_amount": 500, "billed_hours": "12:27", "billed_amount": 500, "un_billed_hours": "00:00", "un_billed_amount": 0, "billable_hours": "12:26", "billable_amount": 500, "non_billable_hours": "0.00", "non_billable_amount": 0, "cost_budget_amount": "1000.00", "is_recurrence_associated": false, "recurring_invoices": [ "string" ], "created_time": "2013-09-18T18:05:27+0530", "show_in_dashboard": true, "tasks": [ { "task_id": "460000000044009", "task_name": "Distribution Analysis", "description": "A simple algorithm is to be tested with vehicle detection application.", "rate": 5000, "budget_hours": "0", "total_hours": "12:26", "billed_hours": "12:27", "un_billed_hours": "00:00", "non_billable_hours": "0.00", "status": "active", "is_billable": true, "task_custom_fields": "" } ] } }

Delete project

Deleting a existing project.
oauthscope : ZohoBooks.projects.DELETE

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/projects/{project_id} -X DELETE

Response Example

{ "code": 0, "message": "The project has been deleted." }

Activate project

Mark project as active.
oauthscope : ZohoBooks.projects.CREATE

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/projects/{project_id}/active -X POST

Response Example

{ "code": 0, "message": "The selected Projects have been marked as active." }

Inactivate a project

Marking a project as inactive.
oauthscope : ZohoBooks.projects.CREATE

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/projects/{project_id}/inactive -X POST

Response Example

{ "code": 0, "message": "The selected projects have been marked as inactive." }

Clone project

Cloning a project.
oauthscope : ZohoBooks.projects.CREATE

Arguments

project_name
string
(Required)
Name of the project. Max-length [100]
description
string
Project description. Max-length [500]

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/projects/{project_id}/clone -X POST -d '{"field":"value","field":"value"}'

Body Parameters

Click to copy
{ "project_name": "Network Distribution", "description": "Distribution for the system of intermediaries between the producer of goods and/or services and the final user" }

Response Example

{ "code": 0, "message": "Project has been cloned successfully.", "project": { "project_id": "460000000044019", "project_name": "REAL TIME TRAFFIC FLUX", "customer_id": "460000000044001", "customer_name": "SAF Instruments Inc", "currency_code": "USD", "description": "A simple algorithm is to be tested with vehicle detection application.", "status": "active", "billing_type": "fixed_cost_for_project", "rate": 5000, "budget_type": " ", "total_hours": "12:26", "total_amount": 500, "billed_hours": "12:27", "billed_amount": 500, "un_billed_hours": "00:00", "un_billed_amount": 0, "billable_hours": "12:26", "billable_amount": 500, "cost_budget_amount": "1000.00", "non_billable_hours": "0.00", "non_billable_amount": 0, "is_recurrence_associated": false, "recurring_invoices": [ "string" ], "created_time": "2013-09-18T18:05:27+0530", "show_in_dashboard": true, "tasks": [ { "task_id": "460000000044009", "task_name": "Distribution Analysis", "description": "A simple algorithm is to be tested with vehicle detection application.", "rate": 5000, "budget_hours": "0", "total_hours": "12:26", "billed_hours": "12:27", "un_billed_hours": "00:00", "non_billable_hours": "0.00", "status": "active", "is_billable": true, "task_custom_fields": "" } ], "users": [ { "user_id": "460000000024003", "is_current_user": true, "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "status": "active", "rate": 5000, "budget_hours": "0", "total_hours": "12:26", "billed_hours": "12:27", "un_billed_hours": "00:00", "cost_rate": "10.00" } ] } }

Assign users

Assign a users to a project.
oauthscope : ZohoBooks.projects.CREATE

Arguments

users
array
Show Sub-Attributes arrow
user_id
string
(Required)
ID of the user to be added to the project.

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/projects/{project_id}/users -X POST -d '{"field":"value","field":"value"}'

Body Parameters

Click to copy
{ "users": [ { "user_id": "460000000024003" } ] }

Response Example

{ "code": 0, "message": "Users added", "users": [ { "user_id": "460000000024003", "is_current_user": true, "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "status": "active", "rate": 5000, "budget_hours": "0", "cost_rate": "10.00" }, {...}, {...} ] }

List Users

Get list of users associated with a project.
oauthscope : ZohoBooks.projects.READ

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/projects/{project_id}/users

Response Example

{ "code": 0, "message": "success", "users": [ { "user_id": "460000000024003", "is_current_user": true, "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "status": "active", "rate": 5000, "budget_hours": "0", "cost_rate": "10.00" }, {...}, {...} ] }

Invite user

Invite and user to the project.
oauthscope : ZohoBooks.projects.CREATE

Arguments

user_name
string
(Required)
Name of the user. Max-length [200]
email
string
(Required)
Email of the user. Max-length [100]
user_role
string
Role to be assigned. Allowed Values: staff, admin and timesheetstaff
rate
string
Hourly rate for a task.
budget_hours
string
Task budget hours.
cost_rate
double

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/projects/{project_id}/users/invite -X POST -d '{"field":"value","field":"value"}'

Body Parameters

Click to copy
{ "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "rate": " ", "budget_hours": "0", "cost_rate": "10.00" }

Response Example

{ "code": 0, "message": "The staff has been added.", "users": [ { "user_id": "460000000024003", "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "is_current_user": true, "cost_rate": "10.00" }, {...}, {...} ] }

Update user

Update details of a user.
oauthscope : ZohoBooks.projects.UPDATE

Arguments

user_name
string
Name of the user. Max-length [200]
user_role
string
Role to be assigned. Allowed Values: staff, admin and timesheetstaff
rate
float
budget_hours
string
Task budget hours.
cost_rate
double

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/projects/{project_id}/users/{user_id} -X PUT -d '{"field":"value","field":"value"}'

Body Parameters

Click to copy
{ "user_name": "John David", "user_role": "admin", "rate": 5000, "budget_hours": "0", "cost_rate": "10.00" }

Response Example

{ "code": 0, "message": "The staff information has been updated.", "users": [ { "user_id": "460000000024003", "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "is_current_user": true, "cost_rate": "10.00" }, {...}, {...} ] }

Get a User

Get details of a user in project.
oauthscope : ZohoBooks.projects.READ

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/projects/{project_id}/users/{user_id}

Response Example

{ "code": 0, "message": "success", "user": { "user_id": "460000000024003", "is_current_user": true, "user_name": "John David", "email": "johndavid@zilliuminc.com", "user_role": "admin", "cost_rate": "10.00" } }

Delete user

Remove user from a project.
oauthscope : ZohoBooks.projects.DELETE

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/projects/{project_id}/users/{user_id} -X DELETE

Response Example

{ "code": 0, "message": "The staff has been removed" }

Post comment

Post comment to a project.
oauthscope : ZohoBooks.projects.CREATE

Arguments

description
string
(Required)
Project description. Max-length [500]

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/projects/{project_id}/comments -X POST -d '{"field":"value","field":"value"}'

Body Parameters

Click to copy
{ "description": "Billing based on task hours" }

Response Example

{ "code": 0, "message": "Comments added.", "comments": [ { "project_id": "460000000044019", "comment_id": "460000000044027", "description": "A simple algorithm is to be tested with vehicle detection application.", "commented_by_id": "460000000024003", "commented_by": "John David", "date": "6:52 PM", "date_description": "19 days ago", "time": "6:52 PM" }, {...}, {...} ] }

List comments

Get comments for a project.
oauthscope : ZohoBooks.projects.READ

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/projects/{project_id}/comments

Response Example

{ "code": 0, "message": "success", "comments": [ { "comment_id": "460000000044027", "project_id": "460000000044019", "description": "A simple algorithm is to be tested with vehicle detection application.", "commented_by_id": "460000000024003", "commented_by": "John David", "is_current_user": true, "date": "6:52 PM", "date_description": "19 days ago", "time": "6:52 PM" }, {...}, {...} ] }

Delete comment

Deleting a comment.
oauthscope : ZohoBooks.projects.DELETE

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/projects/{project_id}/comments/{comment_id} -X DELETE

Response Example

{ "code": 0, "message": "The comment has been deleted." }

List invoices

Lists invoices created for this project.
oauthscope : ZohoBooks.projects.READ

Query Parameters

sort_column
Sort invoices raised. Allowed Values: invoice_number, date, total, balance and created_time

Request Example

Click to copy
$ curl https://books.zoho.com/api/v3/projects/{project_id}/invoices -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "code": 0, "message": "success", "invoices": [ { "invoice_id": "460000000044001", "customer_name": "SAF Instruments Inc", "status": "active", "invoice_number": "INV-00004", "reference_number": " ", "date": "6:52 PM", "due_date": "6:52 PM", "total": "310.75", "balance": "48.75", "created_time": "2013-09-18T18:05:27+0530" }, {...}, {...} ], "page_context": { "page": 10, "per_page": 450, "report_name": "Projects", "has_more_page": false, "sort_order": "D", "sort_column": "created_time" } }