Zoho Cliq REST APIs v3 - A Complete Guide to What's Changed & Why

Zoho Cliq REST APIs v3 - A Complete Guide to What's Changed & Why



APIs are not just consumed by a developer with numerous automations and a series of open browser tabs. They are parsed by LLMs, fed into agent pipelines, and auto-completed by AI coding assistants that have zero tolerance for inconsistency.

A verb tucked into a URL, multiple pagination tokens across each module, inconsistent key naming, etc. These gaps create friction that compounds across every integration built on top of our APIs.

Hence, introducing our new REST API documentation with v3 REST APIs, which act as a comprehensive rule-book detailing proper response structures, error codes, query conventions, URL format and HTTP semantics.

💡
 Switching API Versions

To switch between the two API versions, navigate to the top-right corner of the documentation, where you will find a dropdown menu. We currently support v2 (legacy) and v3 (latest).

Version switcher dropdown showing V2 and V3 (Latest) options in the top-right corner of Zoho Cliq API Docs

Here's what we have upgraded, why it's essential, and what it means for anyone building with Cliq APIs today.

What's new in v3

Along with standardization, v3 APIs ship with a substantial set of new capabilities that address the inconsistencies left by v2.

Platform components management


  • Every platform component now has full CRUD API coverage (schedulers and widgets will be launched soon). Creating deluge or webhook bots, adding a script to handlers, and all of this can be automated.

No more endless search exploration

In v2, "search" meant fetching paginated lists, filtering, and manually applying conditional logic, thereby burning bandwidth. v3 includes dedicated search endpoints for both messages and chats, with rich filtering parameters.

Cliq UI via API

The gap between what the UI could do and what the API could do ends with v3. Like, when a user pins a message, stars a chat, or adjusts a notification preference, your integration hits a dead end.

  • Stars, pins, and chat folders are no longer UI-only gestures; they are proper first-class resources with full CRUD endpoints that fit naturally into the same model as everything else in v3.

New documentation template

Along with the APIs and their standardization, we have revamped the documentation theme that's as dynamic as our APIs.


AI tooling


  1. Interrogate implementation questions, debug edge cases, and more by clicking the AI tools dropdown, which populates the Open in Claude, Open in ChatGPT, Copy as Markdown, and View as Markdown options available on every documentation page.
  1. Launch a Claude or ChatGPT session with the full endpoint schema already loaded in context.

OpenAPI Specification, per resource and as a full bundle


  1. Every module overview page ships a module-specific OAS .yml file, and the complete openapi-all.zip bundle is always one click away.
  1. Feed it into OpenAPI Generator for typed client SDKs, drop it into an LLM for schema-accurate code generation, load it into SwaggerHub for an interactive explorer, or wire it into your CI pipeline for contract testing.

Updated Postman collection

  1. At the top of the documentation, access the Postman collection with the correct method, URL, headers, and body for every endpoint. An OAuth folder handles the full token lifecycle and automatically generates and populates both your access and refresh tokens without any manual setup.

  1. Multi-data center support is added into environment variables, two changes switch the entire collection across the US, EU, IN, AU, JP, and CA. Fork it, pull updates as the API evolves, and keep every customization intact.

Glossary as a single source of truth

All the unique 25+ identifiers (BOT_ID, CHAT_ID, CHANNEL_UNIQUE_NAME, etc.) are defined once, with retrieval guides (e.g., how to retrieve via API and UI, if possible), and they're linked from every endpoint that uses them, so there's no more cross-referencing tabs or guessing what a parameter expects.

Multiple language code examples

  1. cURL, Deluge, Java, JavaScript, Node.js, and Python are available copy-ready on every endpoint. Default is cURL. Use the dropdown to switch between different code examples. Pick your language, copy, and run.
  2. Fun-fact: We've also got you covered with bonus support for C#, C# HTTPClient, Go, and JavaScript XHR 🥳

Endpoint-specific errors


  1. Every endpoint includes a section called "Possible Error Codes." By clicking this section, you can view error codes along with their HTTP status codes and plain-language descriptions. 
  2. The codes in the table match exactly the strings the API uses. The information is presented in an expandable and collapsible format to enhance the user interface and user experience.
  3. The relevant error handling can be done with your custom scripts without parsing or guessing any more

Multiple request body examples, per endpoint


  1. Some endpoints support multiple ways to use them. For those, the documentation ships multiple request body examples, each mapped to a distinct business use case, with its own response example.
  2. Switch between them from the dropdown, understand the intent, and take it straight into your script. No reverse-engineering the schema, no guessing what a field is actually for, every example is a real, working scenario you can adapt and use

Technical Upgrades

Removal of verbs in URL


  1. v2 APIs used verb patterns as placeholders in endpoint URLs (e.g., /resource/create or /resource/delete), and these endpoints are spread across every module.
  2. v3 APIs remove these verb placeholders, so every state transition that previously had a unique endpoint now uses a PUT or PATCH on the resource itself, with the new state included in the request body.

Unified response envelope

v2 responses had no consistent shape: some were bare, some wrapped, some ad hoc per endpoint, and all were different. v3 uses one envelope everywhere.
  1. {  
  2.   "type": "bot",  
  3.   "data": { ... }
  4. }

  5. For list responses, the same envelope extends naturally:
  6. {  
  7.   "type": "bot",
  8.   "next_token": "NTB8MTc1Nj...",
  9.   "sync_token": "NTB8MTc3Nz...",
  10.   "deleted": ["53719000001620003"],
  11.   "data": [ ... ]
  12. }
Type uses dot notation for sub-resources: channel. member, chat.read_status, so the resource type is unambiguous regardless of nesting depth. deleted lists IDs removed since the last sync, enabling cache-consistent incremental sync without polling. You write response-parsing logic once. It works across the entire API.

Uniform pagination

Paginating through v2 APIs was genuinely frustrating. Each module used its own token, and you had to account for every variation, and there was no single pattern you could rely on across the board.

The API surface was fragmented across six different tokens: next_token, sync_token, next_set_token, start_token, next_search_token, and page_number, which meant writing and maintaining module-specific pagination code was simply the norm.



v3 fixes this by replacing all of them with exactly two tokens, used identically across every resource:
  1. next_token: A cursor for forward pagination that works the same way regardless of which resource you are querying.
  2. sync_token: Designed for incremental sync, it returns only the records that have changed since your last request, making it significantly more efficient for keeping local state up to date.
Write your pagination logic once, and it works everywhere.

PATCH as a First-class method

In the v2 API, POST and PUT methods were used for almost everything, including partial updates. However, v3 enforces a more proper usage of HTTP methods. PATCH, in particular, is now utilized correctly and consistently.

This means that when updating two fields on a bot, you no longer need to resend the entire configuration. Instead, you only send what has changed, and the rest remains untouched. 

Example:
  1. PATCH /api/v3/bots/{BOT_ID} 
  2. {  
  3.   "name": "CRM Bot",  
  4.   "scope": "organization"
  5. }

Further additions

  1. URL Nesting: URL nesting is only used when it adds real value. If a parent ID can be understood from the authentication token, it is removed from the URL path. This keeps the URLs clean and avoids redundancy.

  2. Plural resource names: Every resource name in every URL, at every nesting level is plural. Hence predictability at URL level means tooling don't need to special case anything, one common rule is applied everywhere.

  3. Hyphens for multi-word segments: All multi-word segments use hyphens not camelCase, not underscores and no concatenation.
    Example: /api/v3/chats/{CHAT_ID}/pin-messages

  4. Consistent Key Formatting: All request and response keys follow a consistent snake_case format. The mix of camelCase and snake_case from v2 modules has been eliminated. This ensures that generated clients and serialization logic function correctly from the outset.

  5. Field Selection and Sorting: Field selection and sorting are standardized across all list endpoints. You can limit the data returned using "?fields=id, name" and control the order with "?order_by=+created_time", maintaining the same syntax throughout.

  6. Granular OAuth Scopes: OAuth scopes are now more detailed and documented for each endpoint. This allows integrations to request only the permissions they need (READ, CREATE, UPDATE, DELETE), with each endpoint clearly stating the required scope.

And that's a Wrap 🚀 !

v3 is live, but it's not done yet. More modules, endpoints, relevant MCP tools and features are on the way, and they will all meet the same high standards you see here
Thank you for building on Cliq, for pushing us to improve, and for trusting us with your integrations.

Try it out now, and if you have any feedback, suggestions or need help integrating our APIs into your internal workflows, please reach out to support@zohocliq.com, and we'd be happy to help :)

💌 With love,
Team Zoho Cliq
    • Sticky Posts

    • Never miss a follow-up with personal reminder agent | Zoho Cliq AI Use Case #03

      A task mentioned mid-conversation rarely survives the conversation. Someone asks you to follow up, you say you will, and by the time you remember, the message is three hundred lines back, buried under two meetings and a dozen other threads. Personal Task
    • Building an AI Agent for Workplace Occasions | Zoho Cliq AI use case #02

      Some workplace moments happen only once a year, which makes them surprisingly easy to forget. A colleague's birthday, a five-year work anniversary, a team's special milestone - miss the date, and the congratulatory message becomes an apology for being
    • Automate weekly reports from Channels | Zoho Cliq AI use case #01

      Scrolling endlessly through numerous threads in a Cliq channel and manually counting how many have been closed, how long people took to reply, and who actually participated can be tedious. After 20 minutes, you might have a number that no one can verify.
    • Add Claude in Zoho Cliq

      Let’s add a real AI assistant powered by Claude to your workspace this week, that your team can chat with, ask questions, and act on conversations to run AI actions on. This guide walks you through exactly how to do it, step by step, with all the code
    • Zoho Cliq REST APIs v3 : A complete guide to what's changed and why 

      APIs are not just consumed by a developer with numerous automations and a series of open browser tabs. They are parsed by LLMs, fed into agent pipelines, and auto-completed by AI coding assistants that have zero tolerance for inconsistency. A verb tucked
    • Recent Topics

    • WhatsApp Calling Integration via Zoho Desk

      Dear Zoho Desk Team, I would like to request a feature that allows users to call WhatsApp numbers directly via Zoho Desk. This integration would enable sending and receiving calls to and from WhatsApp numbers over the internet, without the need for traditional
    • [ZohoDesk] Improve Status View with a new editeble kanban view

      A kanban view with more information about the ticket and the contact who created the ticket would be valueble. I would like to edit the fields with the ones i like to see at one glance. Like in CRM where you can edit the canvas view, i would like to edit
    • How to resubscribe to email after using unsubscribe link in Zoho

      I was testing the unsubscribe link feature from our contacts module in ZohoCRM and I sent my personal email a version of an email template with the default embedded unsubscribe link to see if it would utilize the "Email Opt Out" field to track un-subscription.
    • No access to contact categories in Zoho Mail Apps

      I have set up a number of contact categories for my organization. When I compose an email using a web browser these categories are visible. When I compose an email using your Android or iOS Apps no contact categories are visible. Is this expected? If
    • Zoho Plug In

      Is there anyone out there who is able to use it? I have seen lots of problems posted, unable to get any satisfactory suppport at the moment!  I would be really appreciate hearing from users that have it installed and working, my team are loosing belief it will ever work. Be great to hear from those that have a more positive experience
    • Outlook to Zoho sync

      I am the admin for our company and I have (1) single user that is having difficulties with her emails syncing. I have found where the problem is, but I don't know 100% if what is happening is how the plug-in works or if it's a setup issue. My boss created
    • Cant' find the CRM plug in for outlook

      I want to be able to tag emails that I have received into accounts. But I can't find the plug in for out look in the other apps section.  Where can I download it from?
    • Problems with Zoho CRM Microsoft Outlook Plug-In (Add-On)

      I am having problems with the Zoho CRM Microsoft Outlook Plug-In.  I was able to install and setup the Plug-In correctly I believe in Microsoft Outlook, but contacts are now being created in Zoho CRM when an email is sent from MS Outlook.  A contact is created and appears under Contacts in Zoho CRM but no other information is populated in the fields; for instance only the name is there (for instance "rfairley" ) which matches the beginning of their email address; but no phone numbers.    Also, other
    • zoho for outlook

      it would be woderfull to be able to add an email to a case, just as it is possible to add an email to a potential Vincent
    • Mail Addon issue

      Hi, I am trying  to make the mail add on feature work without clutter. The issues is that all emails from the contact are being listed in every opportunity that contact is involved in/ linked to.  I want to filter out the emails that are not relevant to the opportunity. It is ok to have all the mails of a contact under in the contact module. But under the opportunity it shall show only the relevant emails. Is there a way i could do this? Atleast if I could manually assign or amend the listed emails
    • Eliminate duplicate tickets in one department using Email Deduplication ​

      Hello everyone, A department can have multiple email addresses designed for different purposes for example, support@zpad.com and help@zpad.com. When a customer sends an email or thread response to both addresses, or includes both in the To, CC, or BCC
    • Feature Request - Copy Reschedule Link

      Hi Bookings Team, I had a client contact me today, to let me know that she can't make a meeting she booked this week. I can't remember if I included a reschedule link in email notifications, but I was thinking that it would be great if I could just open
    • Issue While Rescheduling Interviews in Zoho Recruit

      Dear Zoho Support Team, We are facing an issue with the Interview Rescheduling functionality in Zoho Recruit integrated with Microsoft Teams. Problem Description When an interview is rescheduled through Zoho Recruit: The new interview is created successfully
    • Enhancement Request for Job Publishing Management in Zoho Recruit

      Provide a centralized view to Publish/Unpublish job openings across: - Job Portals - Career Portal - Employee Referral Portal Add filters to view job openings based on: Published to Career Portal Published to Employee Referral Portal Published to specific
    • Mass Update Option for Changing Work Order Owner

      Hello FSM Team/Mr. Abid, We would like to inquire if there is an option to mass update or bulk change the Owner of Work Orders in Zoho FSM. Current Situation: At the moment, the Owner of a Work Order can only be changed individually, which becomes time-consuming
    • Categorize Items with Item Headers

      Hello customers, Did you ever want to classify items based on specific categories to help your customers understand your invoice better? With the new Item Header feature, you can easily categorize items in your invoices and estimates and give them a common title.  Item Headers are available in the Invoices, the Recurring Invoices and the Estimates module. It can be carried forward from estimates to invoices at the time of converting the estimates.  To add an item header: Go to the Estimates, Invoices
    • Careers Site & Job Openings

      Hello, It would be good to have a section in the careers site with past and inactive jobs. On that note, active jobs to automatically move to this section once the target date in the job opening is reached. At the moment, Recruit administrator will have
    • TeamInbox - Configure Email Sending Delay

      Hello, The feature in Zoho Mail to automatically DELAY a sent message by X minutes is a wonderful feature to catch mistakes before they are sent out. Is this possible with TeamInbox? If not, is it on the roadmap to add it in? Thanks
    • Zoho Desk API Custom Module not all data is showing up

      When i get a record by id for my new module: responseDetailed = invokeurl [ url :"https://desk.zoho.eu/api/v1/cm_tickets_CM/" + record.getJSON("id") type :GET parameters:"" connection:"desk_connection" ]; The response doesnt contain all fields, the field
    • Can you sync CRM contacts to TeamInbox?

      Can you sync CRM contacts to TeamInbox? Or at least upload them? From what I can see, you have to enter them manually one at a time.
    • Team Inbox Support Is TERRIBLE

      Team inbox has the worst support team i've ever dealt with. They take forever to reply to your emails/issues, if you even get a reply. They don't have a phone number so you can't talk with anyone. There is clearly bugs in their system and they don't address
    • Introducing ServiceDesk Plus Integration

      Integrate Zoho Sprints with ServiceDesk Plus (SDP), a service management system that wraps IT asset management, IT service management, and configuration database management into a unified solution. With this integration, agile teams can track and manage
    • Request for Backscatter Protection and Filtering Options

      Hello Zoho Support, Recently, my domain has been targeted by an email spoofing/backscatter attack. Attackers are using our legitimate email addresses, particularly one as forged sender addresses when sending messages from unauthorized servers. Our SPF
    • Keeping phone number text format exporting from Books to Sheet

      We have a custom function that copies data from our customers in Books to Sheets. In the process the customers' phone numbers (unless they contain a space) get treated as numeric values, so leading zeros get stripped off, and in some cases scientific
    • print preview

      We are using microsoft edge, till 12 sep we were getting directly print option. Now we are getting this preview option we have to click print option again. How to bypass this-preview option?
    • NOT SYNCING ORGANIZATIONS-ZOHO BOOKS AND ZOHO INVENTORY

      I purchased the zoho books before and again i purchased zoho inventory after 2 day while syncing the orzaniazation i deleted the trial account of inventory and started the new organization on same user. The problem is that the new inventory organization
    • Vehicle Tracking

      we have GPS devices that installed on our vehicles, and we would like to know if it's possible to  get vehicle live location data from the GPS device To Zoho Creator App.   Thank You
    • [Critical] Massive delays with e-mail

      It takes half an hour or longer for emails to arrive or replies to go out! Another thing I have noticed with outgoing e-mails is that I see an error message when I click on "Show original" (tab "HEADER"). If I click on the "CONTENT" tab, the mail body
    • ZOHO CRM APP - SALESINBOX

      Is it possible to access SALESINBOX in the CRM MOBILE APP
    • Cliq iOS can't see shared screen

      Hello, I had this morning a video call with a colleague. She is using Cliq Desktop MacOS and wanted to share her screen with me. I'm on iPad. I noticed, while she shared her screen, I could only see her video, but not the shared screen... Does Cliq iOS is able to display shared screen, or is it somewhere else to be found ? Regards
    • Sheet co-edit: no live presence — also on Collaborate demo?

      Two Sheet co-edit sessions open OK (same document_id, document.edit: true), but there’s no real-time collaboration: no cell highlights, Group Chat → Users stays empty. Writer co-edit works on the same Office Integrator setup. We see the same on the official
    • ZohoのAIエージェント、作り方から使いどころまで。デモとユーザー事例で学ぶ|12/8東京・無料

      ユーザーの皆さま、こんにちは。 ゾーホージャパンの中野です。 12月8日(火)、Zohoコミュニティで初めてとなる「Zoho コミュニティ ユーザー総会 2026」を開催します。 年に一度、ユーザーとZoho社員が集まる総会として、今回は100名規模での開催を予定しています。 ユーザー企業の実践事例、AIエージェント / Zoho MCP のデモ、CRM・Campaignsの活用セッションなど、 日頃の交流会よりも幅広いプログラムをご用意しました。 以前のご案内から新たに予定している内容も含め、当日の見どころをご紹介します。
    • How to sync Organisation Contacts to Android / AES

      After migration form Exchange compatible server, I got Org Contacts: I've turned on EAS Organisation contacts sync. But on my phone they don't appear and there is no contacts folder to select for these contacts. Only personal contacts. They do appear
    • Zoho Inventory | Can't uncheck/turn off Advance Tracking

      Hi, I wanted to know if there's a way to turn off Advanced Tracking (such as Serial Number or Batch Tracking) for an item in Zoho Inventory. I’ve read that you might need to delete associated transactions and clear the opening stock to disable these features.
    • A way to report on all leads for a given month

      Is there a way to report on ALL leads created in one month by source.  I need to include both open, closed lost and converted leads.   Right now I can only see source of non converted lead and cannot find a way to add the converted leads to the same report.   I'm trying to do this to gain insight into my sources of leads, volume in and disposition of each lead.
    • Unable to delete domains from Zoho Campaigns

      This error occurs while deleting a domain "This domain cannot be deleted because we've found $1sender addresses associated to it." But I have no more sender addresses of this domain anymore. I can't delete the domain.
    • Ability to translate Zoho CRM Kiosks

      Hi team, Is support for translating kiosk text and screen names in the Zoho CRM translation tool planned on the roadmap? Thanks,
    • WorkDrive Desktop Sync Is Being Deprecated: Move to WorkDrive TrueSync for a Smarter Experience

      Hi everyone, We are excited to share a better, smarter way to access and manage your files directly from your computer! We’re transitioning from our legacy Desktop Sync app to WorkDrive TrueSync, designed to give you faster performance,greater flexibility,
    • Automating CRM backup storage?

      Hi there, We've recently set up automatic backups for our Zoho CRM account. We were hoping that the backup functionality would not require any manual work on our end, but it seems that we are always required to download the backups ourselves, store them,
    • Account for Cryptocurrency Holdings in Zoho Books/Custom Currencies?

      Hello, I've recently started using Zoho to run my small business and I've really been enjoying all of its features. However, I've been struggling to find a way to account for cryptocurrencies in Zoho Books. My company mines a Cryptocurrency token called
    • Next Page