Get records from Zoho Creator v2.1

Table of Contents

Note: This task is applicable to all services except Zoho Creator.

Overview

The zoho.creator.v2_1.getRecords task retrieves one or more records from a specified report in a Zoho Creator application, based on the given input parameters and configuration.

Note: This integration task is based on the Zoho Creator - Get Records API.

Syntax

<response> = zoho.creator.v2_1.getRecords(<owner_name>, <app_link_name>, <report_link_name>, <configuration>, <connection>);

where:

ParametersData typeDescription
<response>KEY-VALUE

The response returned by Zoho Creator.

Note: This task internally invokes the Zoho Creator API (v2.1) Get Record endpoint. Therefore, the response returned by this task is identical to the API response, including the code, message, and data (record ID or error details). All API-level limits and validations also apply.
<owner_name>TEXT

Specifies the owner of the Zoho Creator application from which records will be fetched.

Note: Name of the application owner can be fetched in the following ways:

  • URL of the application while editing or accessing it. The URL is in the format: app.zohocreator.com/appbuilder/<application_owner>/...
  • Using the system variable - zoho.adminuser
<app_link_name>TEXT

Link name of the application from which the records will be fetched.

Note: Link name of the application can be fetched in the following ways:

  • URL of the application while editing or accessing it. The URL is in the format: app.zohocreator.com/appbuilder/<application_owner>/<application_name>/...
  • Using the system variable - zoho.appname
<report_link_name>TEXT

Link name of the report from which the records will be fetched.

Note: You can fetch link names from the URL while accessing the report. The URL is in the format: app.zohocreator.com/appbuilder/<application_owner>/<application_name>/#Report:<report_link_name>

<configuration>KEY-VALUE

Specifies optional configuration parameters supported by the Get Records API, such as environment, filtering criteria, maximum records, or field selection.

Note: To skip this parameter, provide an empty map as its value. Example: configuration = Map();
<connection>TEXT

Link name of the connection created and connected to your Zoho Creator account.

Note:

  • Add relevant scopes as mentioned in Zoho Creator Add Records API document while creating the connection.
  • Refer to this post for the list of Zoho services that support the connections page.
  • Learn more about connections

Optional parameters for <configuration>)

The following keys can be included within the parameter in the getRecords task. These options allow you to filter, limit, or customize the records retrieved from the report.

ValueData typeDescription
environmentTEXT

Specifies the environment where the record should be created. Accepted values: "development" or "stage".
This parameter is not required for the production environment.

Note: The value is case-sensitive.

criteriaTEXT

Defines a condition used to filter records from the target report. If not specified, the first 200 records will be fetched based on the report’s predefined sorting order.

Example: "Single_Line.contains("Sample Text")"

Note: The criteria parameter cannot be used to filter records in an integration form’s report.

Learn more about defining the criteria

max_recordsNUMBERSpecifies the maximum number of records to retrieve in a single request. Possible values: 200 (default value), 500, 1000
field_configTEXT

Determines which fields are included in the response:

  • "detail_view" - fetches only the fields included in the detailed view layout.
  • "quick_view" - fetches only the fields included in the quick view layout.
  • "custom" - fetches only the specified fields.
  • "all" - fetches the fields included both in the detailed view and quick view layout.

Default value: quick_view

fieldsTEXTComma-separated list of the required field link names to fetch when field_config is provided.

Example

A company uses a Zoho Creator application named Task Management to manage internal tasks raised by customers. The team needs to view all tasks stored in the All_Tasks report for review. To do this, they use the following script, which fetches up to 200 records from the development environment, including only the Task_Name and Task_Description fields.

// Create an empty KEY-VALUE variable to skip optional parameters
otherParams = Map();
otherParams.put("environment", "development");
otherParams.put("max_records", "200");
otherParams.put("criteria", "ID != 0");
otherParams.put("fields", "Task_Name,Task_Description");
otherParams.put("field_config", "custom");

// Write get records integration task
response = zoho.creator.v2_1.getRecords("Shawn","Task_Management","All_Tasks",otherParams,"creator_oauth_connection");

Response Format

Success Response

  • The success response will be returned in the following format:
{
"response": {
"code": 3000,
"data": [
{
"Task_Name": "Priority Task",
"Task_Description": "I need help installing my air conditioner",
"ID": "3605445000000075003"
},
{
"Task_Name": "Support Ticket1",
"Task_Description": "Toaster Configurations",
"ID": "3605445000000065010"
}
]
},
"headers": {
"record_cursor": "b53bc434d414cec8fdd69fabf66a8ee4d5075859618998b091f40940d68e6f59a1fd0e3612b172f293e38e80be50bbb5"
}
}

Failure Response

  • The failure response for incorrect or non-existent application name will be returned in the following format
{ "code": 2892, "message": "No application named found. Please check and try again." }
  • The failure response for incorrect owner name will be returned in the following format
{ "code": 1110, "message": "No workspace named found. Please enter a valid workspace value." }
  • The failure response for incorrect or non-existent report name will be returned in the following format
{ "code": 2894, "message": "No report named found. Please check and try again." }

Things to Know

This task is subject to the general API limits and data validation rules:

  • You can fetch up to 1000 records per request.
  • A maximum of 50 requests per minute is allowed per IP address.
  • Field-level restrictions apply (for example, you cannot set values for system fields such as Auto Number, Formula, File Upload, Signature, etc.).
  • All form validation rules, mandatory fields, and data type constraints still apply when records are created via the API.

For a full list of limits and supported field types, refer to Zoho Creator API v2.1

Related Links