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

    Nederlandse Hulpbronnen


      • Recent Topics

      • Print a price list or price book

        Hi Community. Am I right in concluding that Zoho has no functionality to print a price list from either Zoho CRM, Zoho Inventory or Zoho Books? I won't get stuck on the fact that Zoho doesn't sync price books between Zoho CRM and Books/Inventory (more
      • The Social Wall: October 2026

        Hello everyone This month, we're making it easier to organize your monitoring workspace with Monitor Groups in Zoho Social. Organize your monitor columns into groups You can now organize your monitor columns into custom groups based on your preferences.
      • Field of Lookup - 5 Field Association Limit.

        This query relates to the post at: https://help.zoho.com/portal/en/community/topic/introducing-the-field-of-lookup-in-crm-public-early-access-2023 My simple (and common) scenario: I select an account / customer lookup and want their address pulled into
      • Duplicate Record Creation

        Hello Team, I would like to check whether there are any options available in Zoho FSM to prevent duplicate record creation in the following modules: Assets Companies Contacts Ideally, we would like the system to check for existing records before allowing
      • Feature Request - Electronic submission of tax returns in Canada

        Allow the user to submit Canada Revenue Agency GST/HST returns with NETFILE. Provide the same functionality for provincial revenue agencies for PST/RST remittances. Today Zoho Books only provides the math required to calculate each line, requiring the
      • 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,
      • Files in Teamspaces: keep your team's documents where the work happens

        Release Note: This feature is available for all accounts across all DCs Hello Everyone, A Teamspace is built around a specific team and a shared objective, and it holds the modules and projects that team works with every day. The document that team depends
      • Request for Zoho Desk Version and Module Details

        Kindly help us confirm the version of Zoho Desk currently being used in our portal, along with the module/edition name. We require this information urgently for our internal documentation.
      • ZohoMail_get_mail_attachment corrupts binary attachments (PDFs) over MCP

        Hi all, The Zoho Mail MCP tool ZohoMail_get_mail_attachment returns binary attachments as UTF-8 text, so PDFs come back corrupted and an AI client can't read or save them. What we see: - The response header is content-type: application/octet-stream;charset=UTF-8.
      • Request: Custom CSS Theme

        I would really like a custom CSS theme that enables me to completely customize the look and feel of the survey page based on the typography of my company brand. Unfortunately, there does not appear to be complete customization with existing themes. This
      • KB Articles - Can't See Content or Trigger Immediate Sync

        Once a file has been submitted to the KB, there's no way to check what it actually contains. There's also no way to force an immediate sync with the source document. These are issues when one is developing and testing an agent. It makes troubleshooting
      • Rebrand your CRM with the all-new custom domain mapping setup

        UPDATES TO THIS FEATURE! 19th Jan, 2024 — Custom domain mapping has been made available for portal users in Zoho One and CRM Plus. 23rd June, 2023 — Custom domain mapping has been made available for all users, in all DCs. Hello everyone! We are elated
      • Découvrez le nouveau Zoho Analytics : l’analytique agentique pour toutes les entreprises

        Nous sommes ravis de vous annoncer le lancement du tout nouveau Zoho Analytics ! Cette nouvelle version marque un tournant majeur dans l’évolution de la plateforme. Initialement conçue comme une solution de BI en libre-service permettant de créer des
      • Zia Agents in Zoho CRM: a better way to set up digital employees

        Hello everyone, If you've been using Zia Agents in Zoho CRM, so far using Connections was the only deployment method you're familiar with. You create an agent in Zia Agents (define its objective, write instructions, use tools, add knowledge base) and
      • 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
      • Admin Logging in as another User

        How can a Super Admin login as another user. For example, I have a sales rep that is having issues with their Accounts and I want to view their Zoho Account with out having to do a GTM and sharing screens. Latest Update (27th April 2026): With the early
      • Tool Parameter UI - Freeze Header

        When one has a number of tools with a number of parameters, scrolling down hides the heading information, forcing one to scroll back up to get confirmation which radio button is which: Seems like simply freezing the header would eliminate that issue.
      • Cannot replace custom tools

        This is so incredibly frustrating. Create a tool group. Add your custom schema to create your custom tools. Attach to an Agent. Now you need to update your schema to make an adjustment? You can't edit the schema or even re-upload a new schema. It blocks
      • Testing Tools - Can't View Response

        When adding a custom tool and trying to test it, one can see whether or not the test has a successful http response, but the actual payload cannot be viewed to verify the tool's performance. I thought that's what the little hover link was for, but mousing
      • more native app support for linux

        Dear zoho,pls build additional apps like zoho valt,zoho sheets,zoho show,zoho authenticator apps for linux ,because more and more people are increasing switching to linux this days,
      • Unbundle feature for composite items

        We receive composite items from our vendors and sell them either individually or create other composite items out of them. So, there is a lot of bundling and unbundling involved with our composite items. Previously, this feature was supported in form
      • Quick Reference Guide on join.zoho.com

        Joining a remote session can be difficult for the people who need it the most. Please add a quick reference guide and better documentation that my Grandma can read on the join.zoho.com site. It's not uncommon to spend 10minutes or longer in a session
      • Zoho Projects - Auto Populate Project on Project Invoices

        Hi Projects team, I noticed that when creating an invoice from a Project in Zoho Projects, the project is not selected on the invoice. Is this something which you would consider as a feature request? It seems silly that when you create an invoice from
      • Times prepopulating in Date/Time field on deal records

        Support tells me that there is no workaround to having the time auto-fill on a date/time field in our deal records -- that is HUGELY inconvenient and creates massive opportunity for error. Our deals involve several parts over various days/times, none
      • Email-Data Synchronization with Zoho Analytics

        Hello, Enterprise Support Community! We're excited to announce the availability of Email Data Synchronization with Zoho Analytics! This highly requested enhancement allows you to sync email data from Zoho CRM into Zoho Analytics, making it easier to analyze
      • Multi-Day Installations

        We schedule technicians on multi-day installations. A single appointment from Monday 8 AM through Friday 5 PM counts as 105 working hours, causing false overbooking. We need one appointment spanning five days but only 40 hours counted toward technician
      • Making shared forms available offline

        Hi, We used to be able to have our forms available offline even if it was a shared form. now we can't. Is this a new bug?
      • Zoho Forms API

        Is there any way to get all form entry list using API? Looking forward to hear from you
      • Documents greater than 40MB Preview

        hello, Documents bigger than 40 MB cannot be previewed in WorkDrive Web App or Mobile App. would it be resolved in future?
      • Calendar Booking - Related Deal

        Is it possible to automatically associate a Calendar Booking with an existing Deal in Zoho CRM? We're trying to use the native Calendar Booking feature. Our goal is to send a booking link to a customer from an existing Deal record, so that when the customer
      • Approval Process configuration is now more flexible and fully customizable

        Hello everyone! Approval Process is back with a better user experience that makes it easier to add rules to your processes. This enhancement includes some UI updates that help you create highly structured approval stages—and more. Let's look at the enhancements
      • Kaizen #268: Using Zoho MCP to Build and Configure Zoho CRM Cadences

        Hi everyone! Welcome back to the Kaizen series! In the previous Kaizen posts, Kaizen #265 and Kaizen #266, we explored how Zoho MCP can be used to work with Zoho CRM records, retrieve metadata, customize CRM, configure automation, and even coordinate
      • Deliverability Update: Impact of the Ongoing Microsoft 365 Service Disruption on Email Delivery

        Zoho Campaigns is operating normally. Microsoft is still recovering from a global incident that affects multiple Microsoft 365 services, including Exchange Online and Outlook. If your mailing lists include Microsoft-hosted addresses (@outlook.com, @hotmail.com,
      • Trigger a Workflow Function if an Attachment (Related List) has been added

        Hello, I have a Case Module with a related list which is Attachment. I want to trigger a workflow if I added an attachment. I've seen some topics about this in zoho community that was posted few months ago and based on the answers, there is no trigger
      • Zoho Inventory - Imporoved Order Fulfillment Reporting

        Hi Inventory Team, i've tried to contact you through support@eu.zohoinventory.com but haven't received a response. I am contacting you on behalf of a client. Our client is a car parts wholesale business and we set them up on Zoho Inventory earlier this
      • Say Hello to Telephony in Zoho FSM

        Zoho FSM now brings complete telephony support so your team can manage inbound and outbound calls without switching tabs. Faster responses, smarter routing, and total call visibility—all in one place. Choose the telephony setup that works for you Zoho’s
      • Increasing API Credits

        Hello everyone! Organizations consume Zoho CRM APIs for various business needs, and it's a show-stopper when you exhaust your API credits before the 24-hour rolling window replenishes your credits. To meet your growing needs and help you keep your business
      • [Online Training] Zoho RPA masterclass: Fundamentals, SAP® automation, & AI workflows

        Hello everyone! Greetings from the Zoho RPA Training Team! We're excited to announce our upcoming Online Training on Zoho RPA. Manual, repetitive tasks like entering data, updating spreadsheets, managing files, and extracting information from documents
      • 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.
      • CNIL - Suivi de Pixel

        Bonjour à tous, À la suite de la nouvelle recommandation de la CNIL sur les pixels de suivi dans les e-mails, savez-vous si Zoho Campaigns permet : de conditionner le suivi des ouvertures au consentement de chaque contact ; de proposer un lien permettant
      • Next Page