Zoho: Retrieve records using a COQL query

← Coql operations · Get started

Operation zoho.executecoqlquery

Provider route: POST /crm/v8/coql. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/zoho with npm, or alter-sdk-zoho with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { ZohoIntegration } from "@alter-ai/zoho";

async function execute(input: Parameters<ZohoIntegration["coql"]["executeCoqlQuery"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new ZohoIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.coql.executeCoqlQuery(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_zoho import ZohoIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = ZohoIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.coql.execute_coql_query(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
body	object	Required within parent	Represents the request body for the COQL query execution. Additional keys: not allowed
body.include_meta	array	Optional	Specify the list of metadata types to include in the response. Possible values: fields - Includes field metadata for the SELECT columns in the response. Maximum items: 1 Minimum items: 1
body.include_meta[]	string	Each item	Specifies a metadata type to include in the response. Possible values: fields - Includes field metadata for the SELECT columns in the response. One of: fields
body.select_query	string	Required within parent	Specify the COQL SELECT query to retrieve records. The query must reference module and field API names. Maximum length: 2147483647

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	JSON	Root
$ (anyOf 1)	object	Alternative	Represents the response body for a successful COQL query, containing the matching records and pagination metadata. Additional keys: not allowed
$ (anyOf 1).data	array	Required within parent	Represents the list of records returned by the COQL query. Always returned in the response. Maximum items: 200 Minimum items: 1
$ (anyOf 1).data[]	object	Each item	Represents a single record returned by the COQL query, with field API names as keys and their corresponding values as values. Additional keys: allowed
$ (anyOf 1).fields	object	Optional	Represents the field metadata for each column specified in the SELECT clause. Keys are field API names and values are field configuration objects. Returned only when fields is specified in the include_meta request body parameter. Additional keys: see wildcard field
$ (anyOf 1).fields.*	Model	Additional keys	Expand Retrieve records using a COQL query — response body — data, fields, info fields value
$ (anyOf 1).info	object	Required within parent	Represents the pagination metadata for the query result. Always returned in the response. Additional keys: not allowed
$ (anyOf 1).info.count	JSON	Required within parent
$ (anyOf 1).info.count (anyOf 1)	integer	Alternative	Represents the number of records returned in the current response. Always returned in the response. Format: int32
$ (anyOf 1).info.count (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
$ (anyOf 1).info.more_records	boolean	Required within parent	Indicates whether additional records matching the query are available beyond the current page. Always returned in the response. Possible values: true - More records are available. Use LIMIT and OFFSET to paginate. false - All matching records are included in this response.
$ (anyOf 2)	null	Alternative

Referenced models: Retrieve records using a COQL query — response body — data, fields, info fields value

Schemas

23 more schemas are linked from the tables above, on the schema pages.

Retrieve records using a COQL query — response body — data, fields, info fields value association details lookup field, related field

Field	Type	Presence	Description and constraints
$	object	Root	Represents the association details for a lookup-type field, including the related and lookup field configurations. Additional keys: not allowed
lookup_field	object	Required within parent	Represents the configuration of the lookup field in this association. Additional keys: not allowed
lookup_field.api_name	string	Required within parent	API name of the resource. It will start with alphabets and can contain alphanumeric characters and underscores. Maximum length: 50 Pattern: ^[A-Za-z][A-Za-z0-9_]*$
lookup_field.id	string	Required within parent	Id of the resource. Format: int64
related_field	object	Required within parent	Represents the related field linked to this association. Additional keys: not allowed
related_field.api_name	string	Required within parent	API name of the resource. It will start with alphabets and can contain alphanumeric characters and underscores. Maximum length: 50 Pattern: ^[A-Za-z][A-Za-z0-9_]*$
related_field.id	string	Required within parent	Id of the resource. Format: int64

Retrieve records using a COQL query — response body — data, fields, info fields value multiselectlookup connected details, linking details, related list connected details

Field	Type	Presence	Description and constraints
$	object	Root	Represents the connected module details for the multi-select lookup field. Additional keys: not allowed
field	Model	Required within parent	Expand Retrieve records using a COQL query — response body — data, fields, info fields value multiselectlookup connected details, linking details, related list connected details field
layouts	array	Required within parent	Represents the list of layouts associated with the connected module in the multi-select lookup. Maximum items: 100
layouts[]	object	Each item	Represents a layout entry for the connected module in the multi-select lookup. Additional keys: not allowed
layouts[].api_name	string	Required within parent	API name of the resource. It will start with alphabets and can contain alphanumeric characters and underscores. Maximum length: 50 Pattern: ^[A-Za-z][A-Za-z0-9_]*$
layouts[].id	string	Required within parent	Id of the resource. Format: int64
module	Model	Required within parent	Expand Retrieve records using a COQL query — response body — data, fields, info fields value multiselectlookup connected details, linking details, related list connected details module

Referenced models: Retrieve records using a COQL query — response body — data, fields, info fields value multiselectlookup connected details, linking details, related list connected details field, Retrieve records using a COQL query — response body — data, fields, info fields value multiselectlookup connected details, linking details, related list connected details module

Retrieve records using a COQL query — response body — data, fields, info fields value multiselectlookup connected details, linking details, related list linking details connected lookup field

Field	Type	Presence	Description and constraints
$	object	Root	Represents the connected lookup field in the linking module. Additional keys: not allowed
api_name	string	Required within parent	API name of the resource. It will start with alphabets and can contain alphanumeric characters and underscores. Maximum length: 50 Pattern: ^[A-Za-z][A-Za-z0-9_]*$
field_label	string	Required within parent	Represents the display label of the connected lookup field. Maximum length: 25
id	string	Required within parent	Id of the resource. Format: int64

Retrieve records using a COQL query — response body — data, fields, info fields value convert mapping

Field	Type	Presence	Description and constraints
$	object	Root	Represents the field mapping configuration used when converting a lead to other CRM modules. Additional keys: not allowed
Accounts	JSON	Optional	Represents the Accounts field API name to which this field is mapped during lead conversion.
Accounts (anyOf 1)	string	Alternative	Represents the Accounts field API name to which this field maps during lead conversion. Maximum length: 100
Accounts (anyOf 2)	null	Alternative	Represents the null if no information is available.
Contacts	JSON	Optional	Represents the Contacts field API name to which this field is mapped during lead conversion.
Contacts (anyOf 1)	string	Alternative	Represents the Contacts field API name to which this field maps during lead conversion. Maximum length: 100
Contacts (anyOf 2)	null	Alternative	Represents the null if no information is available.
Deals	JSON	Optional	Represents the Deals field API name to which this field is mapped during lead conversion.
Deals (anyOf 1)	string	Alternative	Represents the Deals field API name to which this field maps during lead conversion. Maximum length: 100
Deals (anyOf 2)	null	Alternative	Represents the null if no information is available.

Retrieve records using a COQL query — response body — data, fields, info fields value email parser

Field	Type	Presence	Description and constraints
$	object	Root	Represents the email parser configuration for the field, indicating which operations are supported through the email parser. Additional keys: not allowed
fields_update_supported	boolean	Required within parent	Indicates whether the field can be updated through the email parser. Possible values: **true** - Field updates are supported by the email parser. **false** - Field updates are not supported by the email parser.
record_operations_supported	boolean	Required within parent	Indicates whether record operations are supported for this field through the email parser. Possible values: **true** - Record operations are supported by the email parser. **false** - Record operations are not supported by the email parser.

Retrieve records using a COQL query — response body — data, fields, info fields value external show, type

Field	Type	Presence	Description and constraints
$	object	Root	Represents the external field configuration, including visibility and type. Additional keys: not allowed
show	boolean	Required within parent	Indicates whether the external field is visible. Possible values: **true** - The external field is visible. **false** - The external field is hidden.
type	string	Required within parent	Represents the type of external field association, such as **org** for organization-level fields. Maximum length: 50

Retrieve records using a COQL query — response body — data, fields, info fields value child fields array item field

Field	Type	Presence	Description and constraints
$	object	Root	Represents the configuration details of the child field. Additional keys: not allowed
api_name	string	Required within parent	API name of the resource. It will start with alphabets and can contain alphanumeric characters and underscores. Maximum length: 50 Pattern: ^[A-Za-z][A-Za-z0-9_]*$
id	string	Required within parent	Id of the resource. Format: int64
name	string	Required within parent	Represents the name of the child field. Maximum length: 100

Retrieve records using a COQL query — response body — data, fields, info fields value formula assume default, dynamic, return type, stop compute conditionally, sub return type

Field	Type	Presence	Description and constraints
$	object	Root	Represents the formula configuration for the field, including return type and computation settings. Additional keys: not allowed
assume_default	boolean	Optional	Indicates whether the formula assumes default values for empty inputs. Possible values: **true** - The formula assumes default values. **false** - The formula does not assume default values.
dynamic	boolean	Optional	Indicates whether the formula is dynamic and recalculated on each access. Possible values: **true** - The formula is dynamic. **false** - The formula is static.
return_type	string	Optional	Represents the data type returned by the formula. Maximum length: 50
stop_compute_conditionally	boolean	Optional	Indicates whether formula computation stops based on a condition. Possible values: **true** - Formula computation stops conditionally. **false** - Formula computation runs to completion.
sub_return_type	string	Optional	Represents the sub-return type of the formula, providing additional type information for string-type formulas. Maximum length: 50

Retrieve records using a COQL query — response body — data, fields, info fields value hipaa compliance restricted, restricted in export

Field	Type	Presence	Description and constraints
$	object	Root	Represents the HIPAA compliance settings for the field. Additional keys: not allowed
restricted	boolean	Required within parent	Indicates whether access to the field is restricted due to HIPAA compliance. Possible values: **true** - Access to the field is restricted. **false** - Access to the field is not restricted.
restricted_in_export	boolean	Required within parent	Indicates whether the field value is restricted from being exported due to HIPAA compliance. Possible values: **true** - The field is restricted in exports. **false** - The field is not restricted in exports.

Retrieve records using a COQL query — response body — data, fields, info fields value multiselectlookup connected details, linking details, related list linking details lookup field

Field	Type	Presence	Description and constraints
$	object	Root	Represents the lookup field in the linking module. Additional keys: not allowed
api_name	string	Required within parent	API name of the resource. It will start with alphabets and can contain alphanumeric characters and underscores. Maximum length: 50 Pattern: ^[A-Za-z][A-Za-z0-9_]*$
field_label	string	Required within parent	Represents the display label of the lookup field. Maximum length: 25
id	string	Required within parent	Id of the resource. Format: int64

Policy, approvals and errors

SDK function policy ID: zoho.executecoqlquery. Catalog operation: executeCOQLQuery. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

No-content response statuses: [204]

Official provider source