Zoho Projects provides a comprehensive set of REST APIs to manage your projects, connect third party applications, and transfer or retrieve data from Zoho Projects.

Zoho Projects APIs require a mandatory header.

1. Authorization : The OAuth access token to authenticate the user accessing data.

Version-3 (V3) builds on the existing Zoho Projects API by introducing a more consistent structure across endpoints and extending support for common integration needs. Updates to areas like date formats, filtering, custom fields, and pagination make it easier to work with data in a predictable way. In this section, you'll find what's new in v3, what has been updated, and what to review when moving from v2.

V3 introduces a more consistent and structured way to work with the Zoho Projects API. It simplifies how data is formatted, how requests are constructed, and how responses are handled, making integrations easier to build and maintain. These updates also bring more clarity when working with filters, custom fields, and large datasets.

All date and time values follow a single ISO 8601 format across endpoints. This ensures consistent parsing and removes the need to handle multiple formats.

The *_long epoch fields are removed. ISO 8601 timestamps are universally parseable.

You can define multiple conditions within a single request using a structured filter object. Filtering is processed entirely on the server, so only relevant records are returned.

• Supported conditions:
  • is
  • is_not
  • contains
  • starts_with
  • before
  • after
  • is_empty
  • is_not_empty
  • between
• Pattern logic: Combine conditions using AND, OR, and grouping - e.g. "(1 OR 2) AND 3"
• Custom field support: Use the api_name of any custom field as the criteria field_name

For the complete syntax reference, see the Filter Guide.

Custom fields now use clear and consistent api_name values. This makes it easier to reference them across requests, filters, and responses without additional mapping.

• Stable references - field identifiers don't shift when other fields are added or removed
• Works everywhere - same api_name in requests, responses, and filter criteria

For full details, see Custom Fields.

The same field structure is used in both requests and responses. This improves predictability and reduces the need for transformation logic when handling API data.

Pagination is now page-based, making it easier to work with large datasets.

• Use page and per_page to control results
• has_next_page indicates if more records are available
• Avoids duplicate or skipped records
• No need for manual offset calculations

For full details and examples, see Pagination.

All endpoints in v3 follow a consistent URL pattern. The base URL is simplified and standardized, and trailing slashes are no longer required. This makes it easier to construct and predict endpoint URLs across the API.

Zoho Projects currently supports the following methods.

Zoho Projects APIs are governed by rate limits to ensure fair usage and optimal performance of all users.

• Each API can be invoked up to 200 times within a 2-minute window.
• The limit is applied per API endpoint.

Each API response includes the following headers to help you monitor your usage:

• RateLimit: Total allowed requests in the current window (e.g., 200).
• RateLimit-Remaining: Remaining requests available in the current window.
• RateLimit-Window: Duration of the rate limit window (e.g., 120 seconds).
• RateLimit-Window-Unit: Time unit for the rate limit window (e.g., seconds).
• Retry-After: Time (in seconds) to wait before retrying the request after the rate limit has been exceeded.

If the number of requests exceeds the allowed limit:

• The specific API will be temporarily blocked for 10 minutes.
• During this period, all further requests to that API will fail.
• A Retry-After header will be included in the response, indicating the remaining time (in seconds) before the API becomes available again.

• The restriction applies only to the API that exceeds the limit, not all APIs.
• After the 10-minute cooldown, the API will become available automatically.
• Continuous violations may impact application performance and reliability.

To avoid hitting rate limits:

• Implement retry mechanisms using the Retry-After header.
• Use exponential backoff instead of immediate retries.
• Avoid sending unnecessary or duplicate requests.
• Use batch APIs (if available) to reduce the number of calls.
• Cache frequently used data whenever possible.

v3 uses page-based pagination on all list endpoints. Pass page and per_page as query parameters to control which page of results is returned.

Every list response includes a page_info block. The has_next_page flag tells your client precisely when to stop fetching — no offset calculations, no risk of duplicate or skipped records.

Understand, locate, and use API names for modules, fields, and related apis in Zoho Projects.

An API name is a unique identifier assigned to every module and field in Zoho Projects.

While display names (labels shown in the UI) can be renamed and may include spaces or special characters, API names provide a consistent reference that remains unchanged across API requests and responses.

API names are used in all programmatic interactions with Zoho Projects.

API names appear as keys in request payloads and response data. Fields such as priority, status, and department are referenced using their API names rather than display labels.

This applies to operations such as creating, updating, retrieving, and filtering records.

API names for modules and fields in Zoho Projects can be accessed through the product or using APIs.

API names for custom fields are available directly within the Fields section in Zoho Projects, alongside other field details.

• Navigate to Setup > Customization > Fields.
• Select the required module.
• Use the Search Fields option to locate a specific field from the Fields list.
• Copy the API name to use it in the API operations.

The Modules API returns metadata for all modules in a portal, including their API names. The Fields API returns metadata for all fields in a module, including API names, data types, and whether a field is custom. Together, they provide a complete reference of available modules and fields for API usage.

• Refer to Get Modules for the list of modules and their API names.
• Refer to Get Fields Info for field-level details including API names.

Send custom field values when creating or updating records through Zoho Projects APIs.

Custom fields are configured within module layouts to capture additional information based on business needs. Use the corresponding field API names to pass values in the request payload.

For example, a checkbox custom field can be used to track a project condition, and its value can be submitted as true or false in the API request.

Zoho Projects supports various custom field types, such as text, numeric, URL, date, and time. Below are the field types available in the Create and Update APIs.

Captures text in a single line. Maximum length: 200 characters

Captures text in multiple lines. Use "\n" to separate lines. Maximum length: 1,000 characters

Allows selection of a single option from a predefined list. Maximum options: 50

Allows selection of multiple options from a predefined list. You can add or remove values dynamically, or replace the existing values. Maximum selectable options: 100

Allows selection of a single user.

Allows selection of multiple users from a predefined list. You can add or remove values dynamically, or replace the existing values. Maximum selectable users: 500

Captures date in the yyyy-MM-dd format (ISO 8601).

Captures the time in HH:MM format.

Captures date and time in ISO 8601 format. Use yyyy-MM-dd'T'HH:mm:ss'Z' for UTC or yyyy-MM-dd'T'HH:mm:ss[+|-]HH:mm for other time zones. (ISO 8601 Time Stamp format).

Captures boolean values (true or false) for a condition.

Captures currency values with currency code, formatted amount, currency ID, and raw amount. Maximum length: 100 characters

Captures percentage values as numbers. Maximum length: 20 characters

Captures whole numbers. Maximum length: 19 digits

Captures decimal values. Maximum length: 17 digits

Captures email addresses. Maximum length: 200 characters

Captures phone numbers (Maximum length: 15 characters, including + and ()).

Captures web links. If no protocol is specified, https:// is used by default. Maximum length: 200 characters

The filter query parameter in Zoho Projects v3 enables retrieving only records that match defined conditions. This approach avoids fetching all records and applying filtering on the client side. This guide explains how to construct filter payloads, available conditions, and supported value formats.

The filter payload is organized into key components that together represent how the conditions are defined and applied within a request : criteria and pattern.

The pattern shows how criteria are combined and evaluated together. Each condition is referenced by its position in the list (starting from 1), and operators like AND, OR are used to define the relationship between them. Parentheses () can be used to group conditions and control how they are applied. The pattern is always required, with "1" used when only a single condition is present.

The value field represents the input used to evaluate a condition and is always structured as an array of strings. It is required for most conditions, while presets do not include a value. Range-based conditions such as between using exactly two values, and the format varies based on the field type.

Used for text-based fields such as name, email, and custom fields, where matching is based on keywords or exact values. All comparisons are case-insensitive.

Used for numeric and date fields, where values are evaluated based on comparisons like greater than, less than, or within a range.

Includes ready-to-use conditions based on dates, evaluated relative to the current date without requiring manual input.

Includes predefined conditions that group records based on their status, such as open or closed.

Used for fields related to users, including assignments, reporting structure, and user-specific states. (requires ZPUID in the value array):

Used to identify fields that do not have any value assigned.

Ready-made filter payloads for the most common requests. Copy a payload, URL-encode it, and pass it as the filter query parameter.

These filters work across modules such as tasks, issues, and custom modules.

Returns all open tasks in a single request.

Uses status with the custom_condition operator and the ${ALL_OPEN} value.

Returns all closed tasks in a single request.

Uses status with the custom_condition operator and the ${ALL_CLOSED} value.

Returns tasks in a specific status.

Uses status with the is condition and the status ID as the value.

Returns tasks owned by a specific user.

Uses owner with the is condition and the user's ZPUID as the value.

Returns tasks whose name contains the given text.

Uses name with the contains condition and the search text as the value.

Returns tasks created after a specific point in time.

Uses created_time with the greater_than condition and a YYYY-MM-DD value.

Returns tasks last updated after a specific date.

Uses last_updated_time with the greater_than condition and a YYYY-MM-DD value.

These filters are available in the Tasks module only.

Returns only subtasks (tasks that have a parent task).

Uses has_parents with value true. Set false to return only top-level tasks. Accepts "true" / "false" or "1" / "0".

Returns the subtasks of a specific parent task.

Uses parent_task with the is condition and the parent task ID as the value.

Returns tasks that belong to a task list whose name contains the given text.

Uses module_name set to tasklist to filter on the related module's name field.

Zoho Projects APIs use OAuth 2.0 for authentication. This page gives you an overview of the authentication process. For complete details on OAuth 2.0 flows, registration, token management, and more, refer to Zoho OAuth 2.0 documentation.

To access Zoho Projects APIs, your application needs an access token obtained through one of the OAuth 2.0 flows. At a high level, the steps are:

1. Register your application in the Zoho API console.
2. Get consent from user to access their data and obtain an access token.
3. Call Zoho Projects APIs using the access token.

Access tokens expire periodically. The expiry duration is returned as expires_in (seconds) in the access token response.

To maintain uninterrupted access, you can request for an optional refresh token, store it, and use it to generate new access tokens as needed.

• Access tokens are required for every API request.
• Refresh tokens can be used to generate new access tokens without requiring user re-authorization.
• Users can revoke an application's access at any time, which invalidates the associated tokens.

For more details on token management, refer to Zoho OAuth 2.0 documentation.

Zoho supports OAuth flows for different application types (server-based, client-based, mobile & desktop-based, limited input devices, and self client). You can choose the flow that matches your application.

For detailed information, refer to the OAuth documentation.

Zoho operates data centers in multiple regions. If your application serves users across regions, you must enable Multi DC support in the API console and use region-specific endpoints for both OAuth and Zoho Projects API calls.

See Multi-DC Support.

Zoho Projects APIs require OAuth scopes to define the level of access your application needs. When requesting for access token, request only the scopes your application requires. These will be displayed to the users when asking for consent.

To request multiple scopes, separate them with commas:

scope=ZohoProjects.projects.READ,ZohoProjects.tasks.ALL

For more details about scope format, see OAuth Scopes.

To authenticate your API calls, include the access token in the Authorization header of every API request with the prefix Bearer.

Authorization: Bearer {access-token-value}

curl -X GET "https://projects.zoho.com/api/v3/portals" -H "Authorization: Bearer 1000.abc123def456..."

Use this method to generate the organization-specific grant token if your application does not have a domain and a redirect URL. You can also use this option when your application is a standalone server-side application performing a back-end job.

1. Go to Zoho Developer Console and log in with your Zoho Projects username and password.
2. Choose Self Client from the list of client types, and click Create Now.
3. Click OK in the pop up to enable a self client for your account.
4. Now, your client ID and client secret are displayed under the Client Secret tab.

5. Click the Generate Code tab and enter the required scope separated by commas. Refer to our list of Scopes, for more details. The system throws an 'Enter a valid scope' error when you enter one or more incorrect scopes.
6. Select the Time Duration for which the grant token is valid. Please note that after this time, the grant token expires.
7. Enter a description and click Create.

8. The organization-specific grant token code for the specified scope is displayed. Copy the grant token.

When making API calls, you must use the base URL corresponding to your user's data center. The access token response identifies the user's data center through the location and api_domain values - use it to pick the matching Zoho Projects base URL from the table below.

• Registering your app in API console
• OAuth glossary
• Token limits
• Incremental authorization
• Sign in using Zoho (OIDC)