Zoho CRM COQL: Advanced record querying with SQL-like syntax

COQL (CRM Object Query Language) brings familiar SQL-style querying to Zoho CRM's API layer, letting developers retrieve precisely the records they need using structured, expressive query statements.

What is it

COQL is Zoho CRM's SQL-like query language exposed through the Query API, enabling developers to write SELECT statements against CRM modules using field and module API names in place of table and column names ^[1]. Unlike the standard Search API, which is scoped to a single module, COQL supports cross-module data retrieval by traversing lookup field relationships — effectively enabling joins across related modules ^[1]. The API supports standard SQL clauses including WHERE, ORDER BY, GROUP BY, LIMIT, and OFFSET, as well as aggregate functions such as SUM(), AVG(), COUNT(), MIN(), and MAX() for in-platform data analysis ^[2].

When to use it

• Cross-module reporting: When you need to pull related data from two or more modules linked by lookup fields — for example, fetching Contact names alongside their parent Account details — in a single API call rather than chaining multiple requests ^[1].
• Aggregate analysis: When you want to calculate totals, averages, or record counts (e.g., total deal value by owner) directly within CRM without exporting data to an external analytics tool ^[2].
• Filtered bulk exports: When you need to retrieve large, criteria-filtered record sets (up to 100,000 records per unique criteria via pagination) for downstream processing or synchronisation ^[7].
• Dynamic application queries: When building Canvas views or developer hub components that require runtime-variable queries — COQL statements support {{VARIABLE_NAME}} placeholders that are resolved at execution time ^[5].
• Precise field selection: When bandwidth or API credit efficiency matters and you want to return only specific fields rather than full record payloads, keeping LIMIT values low to minimise credit consumption ^[7].
• Sorted, paginated data feeds: When an integration needs deterministic, offset-based pagination through a result set, using LIMIT and OFFSET combined with id-based cursor logic to walk beyond the 100,000-record boundary ^[8].

How to access it

COQL queries are submitted via the Query API endpoint using a POST request to /crm/v8/coql, with the query string passed as the select_query key in the JSON request body ^[1]. For no-code or low-code usage within the platform, navigate to Setup → Developer Hub → Queries, create a new query, and choose COQL as the source type; the query editor accepts the same SQL-like syntax and supports variable declarations for dynamic execution ^[5]. Authentication follows standard Zoho CRM OAuth 2.0 flows, and API credit consumption scales with the LIMIT value specified in the query — requests with a limit of 1–200 consume one credit, 201–1,000 consume two credits, and 1,001–2,000 consume three credits per call ^[7].

Related features

• Bulk Read API — preferred over COQL when you need to export more than 100,000 records asynchronously in a single operation, avoiding pagination complexity ^[7].
• GraphQL API — an alternative querying approach that retrieves both CRM data and metadata (modules, roles, profiles) in a single hierarchical call, well-suited when nested sub-resource traversal or schema introspection is required ^[3].
• Search API — a simpler, module-scoped search option for straightforward keyword or criteria-based lookups that do not require cross-module joins or aggregate calculations ^[1].
• Notification API — complements COQL-driven integrations by pushing real-time change events to your endpoint, eliminating the need to poll with repeated COQL queries to detect data updates ^[6].