Get Records - v2.1
The functionality of this task can also be achieved using Get record - Quick View from API V2. But we suggest using API V2.1 for an updated experience.
Updates in V2.1:
1. New Parameters have been added:
- record_cursor parameter key bulk fetches a batch of the consecutive 1000 records.
- field_config parameter key allows you to decide what fields of the records you want to be fetched. Possible values: quick_view, detail_view, custom, all.
- fields parameter key defines the fields that need to be fetched when the custom value is parsed for field_config.
- max_records parameter key decides the number of records that will be fetched per request.
2. Response Structures have been revised:
- In API V2, the display_value of subform and lookup fields in the fetched response included space separated values. Along with this, in V2.1, they are included as key-value pairs in zc_display_value. This helps in efficient parsing of values further.
- In API V2, all multivalue fields had the response structure as space separated values in a string. The response value structures for different fields in API V2.1 have been updated:
- Multiselect, Checkbox: [list_value]
- Single select lookup, Integration: {map}
- Multiselect lookup: [{map1},{map2},{map3}...]
This helps in efficient parsing of values further.
Overview
This API fetches the records displayed by a report. Its response will contain the data of all the visible fields present in the report's records. A maximum of 1000 records can be fetched per request.
Request Details
Request URL
Request Method
GET
Header
Key | Value | Description |
Authorization | Zoho-oauthtoken 1000.8cb99dxxxx xxxxxxxxx9be93.9b 8xxxxxxxxxxxxxxxf | An authentication token (authtoken) allows users to access apps and APIs without having to enter their login credentials each time. |
environment | development/stage | Refers to the environment stage. |
demo_user_name | demouser_1, demouser_2, demouser_3.. | Demo users in your Creator app can be appended along with the environment. |
record_cursor | 78S********p56 | Record cursor is an alpha numeric key. Every time records exist beyond the 1000 fetch count, a unique key will be received in the response header. This can be added in the header of the next API call to fetch the consecutive batch of 1000 records if they exist. |
accept |
| The format in which the API response is displayed. Default value: application/json |
OAuth Scope
base_url | the base URL of your Creator account For example, it's www.zohoapis.com if your account belongs to Zoho's US DC, and is www.zohoapis.eu if it belongs to Zoho's EU DC. |
account_owner_name | the username of the Creator account's owner |
app_link_name | the link name of the target application |
report_link_name | the link name of the target report |
Parameters
criteria string
(Optional)
The criteria using which you want the API request to filter the target report. If not specified, the request will fetch the first 200 records from the report (as per its predefined sorting order). The sample input on the right sports a criteria that'll filter for records where the Single_Line field contains the value "Single Line of Text". Refer to the section below to learn more about defining the criteria.field_config string
(Optional)
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
Note:
- This API will not fetch the records displayed in the related data blocks of the detail view.
- If the key value is given as custom, the fields key should also be included in the header.
fields string
(Optional)
All the required fields' link names as individual comma-separated strings.Note: The field link names can be found in the field properties pane of each field in the form builder.max_records int
(Optional)
The number of maximum records that will be fetched upon one request.
Possible values: 200 (default value), 500, 1000Note: For integration forms' reports, the maximum fetch count defined by the other service will be followed. Therefore, this parameter need not be included. If the number of records exceeds the defined limit, the record_cursor header key to fetch the next batch will be received in the response.
Defining the search criteria
The search criteria is a combination of one or more expressions. An expression is defined using a field, operator, and value.
An expression can use all field types except section and add notes. The field's data type dictates the operator that can be used and the format in which the value is to be given.
You can use logical operators && (AND) and || (OR) to link the expressions in your criteria. These operators are subject to precedence, which you can manage using parentheses ().
Values for STRING type fields, such as single line, email, and phone, must be enclosed in double-quotes.
Values for the time, date, and date-time fields must adhere to the application's date and time formats and must be enclosed in single-quotes.
The record ID must be passed when you want to filter the records using the lookup and integration fields.
When using the multi select, checkbox or multi-select lookup fields, you can specify only one value per expression.
Sample value for the parameter "criteria" | Description |
Name.last_name == "Boyle" | To fetch the records where the last name is Boyle |
Name.last_name != "" | To fetch the records where the last name is not empty |
Name.first_name.startsWith("Pat") | To fetch the records where the first name starts with "pat", such as Patricia and Patrick |
Email_Address.endsWith("zylker.com") | To fetch the records where the email address ends with zylker.com |
Feedback.contains("it's awesome") | To fetch the records where the feedback (a multi line field) contains the phrase "it's awesome" |
Total = 250.00 | To fetch the records where the total (a currency field) is equal to 250.00 |
Total >= 100.00 | To fetch the records where the total (a currency field) is greater than or equal to 100.00 |
Total < 50 | To fetch the records where the total (a decimal field) is less than 50 |
Appointment_Date = '13-Apr-2020' | To fetch the records where the appointment date (a date field) is 13-Apr-2020 (as per the application's date format) |
Appointment_Date >= '13-Apr-2020' && Appointment_Date <= '18-Apr-2020' | To fetch the records where the appointment date (a date field) ranges from 13-Apr-2020 to 18-Apr-2020 |
Order_Status=="Open" || Order_Status=="In-progress" | To fetch the records where the order status (a drop down or radio field) is either Open or In-progress |
Status == "Open" && Total > 250.00 | To fetch the records where the status (a drop down field) is Open and Total (a currency field) is greater than 250.00 |
Product == 3888832000000113058 | To fetch the records where the product (a single-select lookup field) equals 3888832000000113058 (ID of a record present in the looked-up form) |
Expedited_Delivery=false | To fetch the records where the expedited delivery (a decision box field) is false |
Hobbies.contains("Reading") | To fetch the records where the hobbies (a multi select or checkbox field) includes reading |
Hobbies="Reading" && Hobbies="Hiking" | To fetch the records where the hobbies (a multi select or checkbox field) are reading and hiking |
Possible Errors
Refer to this page for the list of error codes and messages.
Sample Request for Production environment (for C6 users)
Copiedcurl "https://www.zohoapis.com/creator/v2.1/data/jason18/zylker-store/report/All_Orders"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
Copiedtry
{
response = invokeUrl
[
url: "https://www.zohoapis.com/creator/v2.1/data/jason18/zylker-store/report/All_Orders?max_records=200&criteria=Single_Line%20%3D%3D%20%22Single%20Line%20of%20Text%22&field_config=custom&fields=Single_Line%2CNumber"
type: GET
connection: "creatorconnection"
];
}
catch(e)
{
info "Exception while making the API request." ;
}
Copiedpackage org.example;
import okhttp3.HttpUrl;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import org.json.JSONObject;
public class GetRecords
{
public static void main(String[] args)
{
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://www.zohoapis.com/creator/v2.1/data/jason18/zylker-store/report/All_Orders").newBuilder()
.addQueryParameter("max_records", "200")
.addQueryParameter("criteria", "Single_Line == \"Single Line of Text\"")
.addQueryParameter("field_config","custom")
.addQueryParameter("fields","Single_Line,Number");
Request request = new Request.Builder()
.url(urlBuilder.toString())
.method("GET", null)
.addHeader("Authorization", "Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf")
.build();
try
{
JSONObject response = new JSONObject(client.newCall(request).execute().body().string());
}
catch (Exception e)
{
System.out.println("Exception while making the API request.");
}
}
}
Copiedlet api_headers = {
"Authorization": "Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
}
try {
let response = fetch("https://www.zohoapis.com/creator/v2.1/data/jason18/zylker-store/report/All_Orders?max_records=200&criteria=Single_Line%20%3D%3D%20%22Single%20Line%20of%20Text%22&field_config=custom&fields=Single_Line%2CNumber", {
method: "GET",
headers: api_headers
})
}
catch (exception) {
console.error(exception)
}
Copiedimport requests
api_parameters = {
"max_records": "200",
"criteria": "Single_Line == \"Single Line of Text\"",
"field_config": "custom",
"fields": "Single_Line,Number"
}
api_headers = {
"Authorization": "Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
}
try:
response = requests.get("https://www.zohoapis.com/creator/v2.1/data/jason18/zylker-store/report/All_Orders", params=api_parameters, headers=api_headers)
except:
print("Exception while making the API request.")
This sample request will fetch the first 1000 records displayed by the All Orders report of the Zylker Store application.
Sample Request for Development/ Stage environments (for C6 users)
Copiedcurl "https://www.zohoapis.com/creator/v2.1/data/jason18/zylker-store/report/All_Orders"
-X GET
-H 'Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf'
-H 'environment: development'
-H 'demo_user_name: demouser_1'
Sample Response: All field types
Copied{
"code": 3000,
"data": [
{
"ID": "52129000008009043",
"Single_Line": "Warehouse",
"Email": "John@Lord.com",
"Currency": "1234723.90",
"Name": {
"zc_display_value": "John Lord",
"prefix": "",
"last_name": "Lord",
"suffix": "",
"first_name": "John"
},
"Address": {
"zc_display_value": "6, West Street, Phoenix, Phoenix, Arizona, 20532, USA",
"country": "USA",
"district_city": "Phoenix",
"address_line_1": "6, West Street",
"state_province": "Arizona",
"address_line_2": "Phoenix",
"postal_code": "20532"
},
"Image": "/api/v2.1/christinaclover/import/report/sample_report/52129000008009043/Image/download?filepath=1681379407888_John.jpeg",
"test_ss": {
"zc_display_value": "52129000008009170 - 13-Apr-2023 17:21:24 - christinaclover",
"Added_User": "christinaclover",
"ID": "52129000008009170",
"Added_Time": "13-Apr-2023 17:21:24"
},
"test_ss.Single_Line": "Portia",
"test_ss.Name": {
"zc_display_value": "Portia Lance",
"prefix": "",
"last_name": "Lance",
"suffix": "",
"first_name": "Portia"
},
"test_ms": [
{
"zc_display_value": "52129000008009051 - christinaclover - John - 13-Apr-2023 16:59:29",
"Modified_Time": "13-Apr-2023 16:59:29",
"Added_User": "christinaclover",
"ID": "52129000008009051",
"Name.first_name": "John"
},
{
"zc_display_value": "52129000008009170 - christinaclover - Portia - 13-Apr-2023 18:03:05",
"Modified_Time": "13-Apr-2023 18:03:05",
"Added_User": "christinaclover",
"ID": "52129000008009170",
"Name.first_name": "Portia"
}
],
"test_ms.Single_Line": [
"test",
"Portia"
],
"test_ms.Name": [
{
"zc_display_value": "John Lord",
"prefix": "",
"last_name": "Lord",
"suffix": "",
"first_name": "John"
},
{
"zc_display_value": "Portia Lance",
"prefix": "",
"last_name": "Lance",
"suffix": "",
"first_name": "Portia"
}
],
"SubForm": [
{
"zc_display_value": "John Lord 220B, Baker Street, London, London, 13455, United Kingdom 10-Apr-2023 52129000008009051 52129000008009051, 52129000008009084",
"Date_field": "10-Apr-2023",
"Address": {
"zc_display_value": "220B, Baker Street, London, London, 13455, United Kingdom",
"country": "United Kingdom",
"district_city": "London",
"address_line_1": "220B, Baker Street",
"state_province": "London",
"address_line_2": "",
"postal_code": "13455"
},
"test": {
"zc_display_value": "52129000008009051",
"ID": "52129000008009051"
},
"test_ms": [
{
"zc_display_value": "52129000008009051",
"ID": "52129000008009051"
},
{
"zc_display_value": "52129000008009084",
"ID": "52129000008009084"
}
],
"ID": "52129000008009023",
"Name": {
"zc_display_value": "John Lord",
"last_name": "Lord",
"first_name": "John"
}
},
{
"zc_display_value": " ",
"Date_field": "",
"Address": {
"zc_display_value": "",
"country": "",
"district_city": "",
"address_line_1": "",
"state_province": "",
"address_line_2": "",
"postal_code": ""
},
"test": {},
"test_ms": [],
"ID": "5213456789000987"
}
],
"Users_MS": [
"christinaclover",
"manish.koothrapalli"
]
}
]
}