GET Records

Purpose

A record is an entity which stores all the combined information of a particular contact or company, which is acquired from various sources. The information may be acquired from a web-form, social media services, advertisements etc. The records API allows the user to get, create, update, delete, or search records.

To retrieve the records that match your search criteria.

Endpoints

GET /{module_api_name}

GET /{module_api_name}/{record_id}

Request Details

Request URL

{api-domain}/crm/{version}/{module_api_name}

Supported modules

Leads, Accounts, Contacts, Deals, Campaigns, Tasks, Cases, Events, Calls, Solutions, Products, Vendors, Price Books, Quotes, Sales Orders, Purchase Orders, Invoices, Custom, and Activities

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

If-Modified-Since: 2019-07-25T15:26:49+05:30

Scope

scope=ZohoCRM.modules.ALL
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names

leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom, and activities.

Possible operation types

ALL - Full access to the record
READ - Get records from the module

Parameters

fieldsstring
To list all the module records with respect to fields.
Possible values: Multiple field API names, comma separated. For example: Last_Name,Email.
sort_orderstring
To sort the available list of records in either ascending or descending order.
Possible values: asc - ascending order, desc - descending order.
sort_bystring
To sort the available list of records based on the given field.
Possible values: Field API name. Example: Email.
convertedstring
To get the list of converted records. Default value is false.
Possible values: true - get only converted records, false - get only non-converted records, both - get all records.
approvedstring
To get the list of approved records. Default value is true.
Possible values: true - get only approved records, false - get only records which are not approved, both - get all records.
pageinteger
To get the list of records from the respective pages. Default value is 1.
Possible values: Positive Integer values only.
per_pageinteger
To get the list of records available per page. The default and the maximum possible value is 200.
Possible values: Positive Integer values only.
cvidlong
To get the list of records based on custom views.
Possible values: {custom_view_id}.
territory_idinteger
To get the list of records based on the territory.
Possible values: {territory_id}.
include_childboolean
To include records from the child territories.Default value is false.
Possible values: true - includes child territory records, false - does not include child territory records.

Note

sort_order applies to given sort_by field.
If sort_by field is not provided, then it applies to the system-defined field.
The page and per_page parameter is used to fetch records according to their position in the CRM. Let's assume that the user has to fetch 400 records. The maximum number of records that one can get for an API call is 200. So, for records above the 200th position, they cannot be fetched. By using the page (1, 2) and per_page (200) parameter, the user can fetch all 400 records using 2 API calls.
While retrieving multiple records, subform records are not retrieved. Only the records count in a subform is retrieved.
To get the record details in a subform, you need to fetch the specific record information in a module.
Only while fetching a specific record from one of the inventory modules, the response will contain one of the following subforms:
- Quoted_Items (for a Quote)
- Invoiced_Items (for an Invoice)
- Ordered_Items (for a Sales Order)
- Purchased_Items (for a Purchase Order)
The $has_more JSON object in the response renders the API names of the multi-select lookup fields in the module with boolean values to indicate whether or not there are more records in these fields in the module. This key is rendered in the response only when you fetch a specific record.
Use the $event_cancelled key in the fields param to retrieve the cancellation status of the Meeting. The $event_cancelled key in the response represents the cancellation status of the Meeting.
To get the list of territories enabled for your organization, refer to the Territories API.
Territory is supported only for the modules Deals, Contacts, and Accounts.
Only admin users can fetch the records from the Notes module. The system throws an error when non-admin users try to fetch the records from the Notes module.
The value of the fields with sensitive health data will be retrieved only when Restrict Data access through API option in the compliance settings is disabled. If the option is enabled, the value will be null. Refer to HIPAA compliance for more details.

Sample Request

Curl PHP Ruby

Copiedcurl "https://www.zohoapis.com/crm/v2.1/Leads/1306462000000888026"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

4.0.04.x

Copied//Get instance of RecordOperations Class
$recordOperations = new RecordOperations();
//Get instance of ParameterMap Class
$paramInstance = new ParameterMap();
// $paramInstance->add(GetRecordParam::approved(), "false");
// $paramInstance->add(GetRecordParam::converted(), "false");
// $fieldNames = array("Deal_Name", "Company");
// foreach($fieldNames as $fieldName)
// {
// 	$paramInstance->add(GetRecordParam::fields(), $fieldName);
// }
// $startdatetime = date_create("2020-06-27T15:10:00");
// $paramInstance->add(GetRecordParam::startDateTime(), $startdatetime);
// $enddatetime = date_create("2020-06-29T15:10:00");
// $paramInstance->add(GetRecordParam::endDateTime(), $enddatetime);
// $paramInstance->add(GetRecordParam::territoryId(), "34770613051357");
// $paramInstance->add(GetRecordParam::includeChild(), "true");
$headerInstance = new HeaderMap();
// $ifmodifiedsince = date_create("2020-06-02T11:03:06+05:30")->setTimezone(new \DateTimeZone(date_default_timezone_get()));
// $headerInstance->add(GetRecordHeader::IfModifiedSince(), $ifmodifiedsince);
//Call getRecord method that takes paramInstance, moduleAPIName and recordID as parameter
$response = $recordOperations->getRecord( $recordId,$moduleAPIName,$paramInstance, $headerInstance);



//Get instance of RecordOperations Class that takes moduleAPIName as parameter
$recordOperations = new RecordOperations();
$paramInstance = new ParameterMap();
// $paramInstance->add(GetRecordsParam::approved(), "true");
// $paramInstance->add(GetRecordsParam::converted(), "1234");
// $paramInstance->add(GetRecordsParam::cvid(), "34770610089005");
// $ids = array("34770615623115", "34770614352001");
// foreach($ids as $id)
// {
// 	$paramInstance->add(GetRecordsParam::ids(), $id);
// }
// $paramInstance->add(GetRecordsParam::uid(), "34770615181008");
// $fieldNames = array("Last_Name", "City");
// foreach($fieldNames as $fieldName)
// {
	// $paramInstance->add(GetRecordsParam::fields(), "id");
// }
// $paramInstance->add(GetRecordsParam::sortBy(), "Email");
// $paramInstance->add(GetRecordsParam::sortOrder(), "desc");
// $paramInstance->add(GetRecordsParam::page(), 1);
// $paramInstance->add(GetRecordsParam::perPage(), 3);
// $startdatetime = date_create("2020-06-27T15:10:00+05:30")->setTimezone(new \DateTimeZone(date_default_timezone_get()));
// $paramInstance->add(GetRecordsParam::startDateTime(), $startdatetime);
// $enddatetime = date_create("2020-06-29T15:10:00+05:30")->setTimezone(new \DateTimeZone(date_default_timezone_get()));
// $paramInstance->add(GetRecordsParam::endDateTime(), $enddatetime);
// $paramInstance->add(GetRecordsParam::territoryId(), "34770613051357");
// $paramInstance->add(GetRecordsParam::includeChild(), true);
$headerInstance = new HeaderMap();
// $datetime = date_create("2021-02-26T15:28:34+05:30")->setTimezone(new \DateTimeZone(date_default_timezone_get()));
// $headerInstance->add(GetRecordsHeader::IfModifiedSince(), $datetime);
//Call getRecords method
$response = $recordOperations->getRecords($moduleAPIName, $paramInstance, $headerInstance);

Copied<?php
class GetRecords{
    
    public function execute(){
        $curl_pointer = curl_init();
        
        $curl_options = array();
        $url = "https://www.zohoapis.com/crm/v2.1/Leads?";
        $parameters = array();
        $parameters["page"]="1";
        $parameters["per_page"]="2";
        $parameters["sort_by"]="Email2";
        $parameters["sort_order"]="desc2";
        $parameters["include_child"]="false";

        
        foreach ($parameters as $key=>$value){
            $url =$url.$key."=".$value."&";
        }
        $curl_options[CURLOPT_URL] = $url;
        $curl_options[CURLOPT_RETURNTRANSFER] = true;
        $curl_options[CURLOPT_HEADER] = 1;
        $curl_options[CURLOPT_CUSTOMREQUEST] = "GET";
        $headersArray = array();
        $headersArray[] = "Authorization". ":" . "Zoho-oauthtoken " ."1000.30f3a589XXXXXXXXXXXXXXXXXXX4077.dc5XXXXXXXXXXXXXXXXXXXee9e7c171c";
        $headersArray[] = "If-Modified-Since".":"."2021-10-12T17:59:50+05:30";
        $curl_options[CURLOPT_HTTPHEADER]=$headersArray;
        
        curl_setopt_array($curl_pointer, $curl_options);
        
        $result = curl_exec($curl_pointer);
        $responseInfo = curl_getinfo($curl_pointer);
        curl_close($curl_pointer);
        list ($headers, $content) = explode("\r\n\r\n", $result, 2);
        if(strpos($headers," 100 Continue")!==false){
            list( $headers, $content) = explode( "\r\n\r\n", $content , 2);
        }
        $headerArray = (explode("\r\n", $headers, 50));
        $headerMap = array();
        foreach ($headerArray as $key) {
            if (strpos($key, ":") != false) {
                $firstHalf = substr($key, 0, strpos($key, ":"));
                $secondHalf = substr($key, strpos($key, ":") + 1);
                $headerMap[$firstHalf] = trim($secondHalf);
            }
        }
        $jsonResponse = json_decode($content, true);
        if ($jsonResponse == null && $responseInfo['http_code'] != 204) {
            list ($headers, $content) = explode("\r\n\r\n", $content, 2);
            $jsonResponse = json_decode($content, true);
        }
        var_dump($headerMap);
        var_dump($jsonResponse);
        var_dump($responseInfo['http_code']);
        
    }
    
}
(new GetRecords())->execute();

2.1.0

Copied# Get instance of RecordOperations Class
ro = Record::RecordOperations.new
# Get instance of ParameterMap Class
pm = ParameterMap.new
# module_api_name = "Leads"
# record_id = 3524033000005662018
# pm.add(Record::RecordOperations::GetRecordParam.approved,"false")
# pm.add(Record::RecordOperations::GetRecordParam.converted,"false")
# field_names =["Company","Email"]
# field_names.each do |field_name|
# pm.add(Record::::RecordOperations::GetRecordParam.fields,field_name)
# end
# Get instance of HeaderMap Class
hm = HeaderMap.new
# hm.add(Record::RecordOperations::GetRecordHeader.If_modified_since,"")
# Call getRecord method that takes param_instance, header_instance, module_api_name and record_id as parameter
response = ro.get_record(record_id,module_api_name,pm, hm)



# Get instance of RecordOperations Class
ro = Record::RecordOperations.new
# Get instance of ParameterMap Class
pm = ParameterMap.new
# record_id = 3524033000005495066
# Add the per_page to ParameterMap instance
pm.add(Record::RecordOperations::GetRecordsParam.per_page, 1)
pm.add(Record::RecordOperations::GetRecordsParam.converted, 'false')
# field_names =["Company","Email"]
# field_names.each do |field_name|
# pm.add(Record::::RecordOperations::GetRecordParam.fields,field_name)
# end
# Get instance of HeaderMap Class
hm = HeaderMap.new
# hm.add(Record::RecordOperations::GetRecordHeader.If_modified_since,"")
# Call getRecords method that takes ParameterMap Instance, HeaderMap Instance and module_api_name as parameters
response = ro.get_records(module_api_name,pm, hm)

Copiedrequire 'net/http'
require 'json'

class GetRecords 

    def execute
        parameters ={}
        parameters["per_page"]="2";
        parameters["page"]="1";
        parameters["sort_by"]="Email2";
        parameters["sort_order"]="desc2";
        parameters["include_child"]="false";
        query_string = parameters.to_a.map { |x| "#{x[0]}=#{x[1]}" }.join('&')
        url= "https://www.zohoapis.com/crm/v2.1/Leads"
        url += '?' + query_string if !query_string.nil? && (query_string.strip != '')
        url = URI(url)
        req = Net::HTTP::Get.new(url.request_uri)
        http = Net::HTTP.new(url.host, url.port)
        http.use_ssl = true
        headers={}
        headers["Authorization"]="Zoho-oauthtoken 1000.dfa7XXXXXXXXXXXXXXXXXX84f9665840.c176aeXXXXXXXXXXXX13f3d37a84d"
        headers["If-Modified-Since"]="2019-10-12T17:59:50+05:30"
        headers&.each { |key, value| req.add_field(key, value) }
        response=http.request(req)
        status_code = response.code.to_i
        headers = response.each_header.to_h
        print status_code
        print headers
        unless response.body.nil?
            print  response.body
        end
    end
end
GetRecords.new.execute

Sample Response

Copied{
    "data": [
        {
            "Owner": {
                "name": "Patricia Boyle",
                "id": "1306462000000374001",
                "email": "p.boyle@abc.com"
            },
            "Company": "SolutionsTech",
            "Email": null,
            "$currency_symbol": "$",
            "$field_states": null,
            "$sharing_permission": "full_access",
            "Last_Activity_Time": "2022-02-03T10:55:15+05:30",
            "Industry": null,
            "$state": "save",
            "Unsubscribed_Mode": null,
            "$converted": false,
            "$process_flow": false,
            "Test": null,
            "Street": null,
            "Data_Processing_Basis_Details": null,
            "Zip_Code": null,
            "id": "1306462000000888026",
            "Data_Source": "API",
            "$approved": true,
            "$approval": {
                "delegate": false,
                "approve": false,
                "reject": false,
                "resubmit": false
            },
            "$data_source_details": {},
            "Created_Time": "2022-02-02T17:09:49+05:30",
            "$wizard_connection_path": null,
            "$editable": true,
            "City": null,
            "No_of_Employees": null,
            "Related": [],
            "State": null,
            "Country": null,
            "Created_By": {
                "name": "Patricia Boyle",
                "id": "1306462000000374001",
                "email": "p.boyle@abc.com"
            },
            "Annual_Revenue": null,
            "Secondary_Email": null,
            "Description": null,
            "Rating": null,
            "$review_process": {
                "approve": false,
                "reject": false,
                "resubmit": false
            },
            "Website": null,
            "Twitter": null,
            "Information": null,
            "$canvas_id": null,
            "Salutation": null,
            "Marital_Status_1": null,
            "Birthday_1": null,
            "First_Name": null,
            "Full_Name": "Sam",
            "Lead_Status": null,
            "Record_Image": null,
            "Modified_By": {
                "name": "Patricia Boyle",
                "id": "1306462000000374001",
                "email": "p.boyle@abc.com"
            },
            "$review": null,
            "Lead_Conversion_Time": null,
            "Skype_ID": null,
            "Phone": null,
            "Lead_Class": "Class S",
            "Email_Opt_Out": false,
            "Designation": null,
            "Modified_Time": "2022-02-03T10:55:15+05:30",
            "$converted_detail": {},
            "Unsubscribed_Time": null,
            "Referred_By": null,
            "Mobile": null,
            "$orchestration": false,
            "$stop_processing": false,
            "Last_Name": "Sam",
            "Layout": {
                "id": "1306462000000095055"
            },
            "$in_merge": false,
            "Lead_Source": null,
            "Tag": [],
            "Fax": null,
            "$approval_state": "approved",
            "Wizard": null,
            "$has_more": {
                "Related": false
            }
        }
    ]
}

Converted Records

To retrieve the converted records, the converted parameter should be true or both. The converted_detail key in the response renders the conversion details which includes the deal (deal id), convert_date, contact (converted contact id), converted_by and account (account id). Please refer to the sample response for more details.

Possible Errors

INVALID_MODULEHTTP 400
The module name given seems to be invalid.
Resolution: Specify a valid module API name. Refer to possible modules section above.
INVALID_MODULEHTTP 400
The given module is not supported in API.
Resolution: The modules such as Documents and Projects are not supported in the current API. (This error will not be shown, once these modules are supported). Specify a valid module API name. Refer to possible modules section above.
INVALID_MODULEHTTP 400
Territory is not supported for the given module.
Resolution: The given module is not territory-supported. Territory is supported only for the modules Deals, Contacts, and Accounts.
NOT_SUPPORTEDHTTP 403
This API is supported only for admin users.
Resolution: Only admin users can fetch records from the Notes module.

Sample request

Copiedcurl "https://www.zohoapis.com/crm/v2.1/Leads?converted=true&approved=true"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

Sample Response

Copied{
    "data": [
        {
            "Owner": {
                "name": "Patricia Boyle",
                "id": "1306462000000374001",
                "email": "p.boyle@abc.com"
            },
            "Company": null,
            "Email": "j.smith@xyz.com",
            "$currency_symbol": "$",
            "$field_states": null,
            "Last_Activity_Time": "2021-10-05T14:37:26+05:30",
            "Industry": "Service Provider",
            "$state": "save",
            "Unsubscribed_Mode": null,
            "$converted": true,
            "$process_flow": false,
            "Test": null,
            "Street": "37275 St Rt 17m M",
            "Data_Processing_Basis_Details": null,
            "Zip_Code": "11953",
            "id": "1306462000000391002",
            "Data_Source": "API",
            "$approved": true,
            "$approval": {
                "delegate": false,
                "approve": false,
                "reject": false,
                "resubmit": false
            },
            "$data_source_details": {},
            "Created_Time": "2021-08-24T14:52:07+05:30",
            "$editable": true,
            "City": "Middle Island",
            "No_of_Employees": null,
            "State": "NY",
            "Country": "United States",
            "Created_By": {
                "name": "Patricia Boyle",
                "id": "1306462000000374001",
                "email": "p.boyle@abc.com"
            },
            "Annual_Revenue": 850000,
            "Secondary_Email": null,
            "Description": null,
            "Rating": null,
            "$review_process": {
                "approve": false,
                "reject": false,
                "resubmit": false
            },
            "Website": "http://www.rangoniofflorence.com",
            "Twitter": "christophermaclead_sample",
            "Information": null,
            "Salutation": "Mr.",
            "Marital_Status_1": null,
            "Birthday_1": null,
            "First_Name": "Jim",
            "Full_Name": "Mr. Jim Smith",
            "Lead_Status": "Lost Lead",
            "Record_Image": "02b9e93996ad174d0c685bd56b94e9d760497ba52e17145a73c18292ae60c1d81915036312ccaf1faaf8c8168eeff1cf427c96c3020bcd3da31280be451e09164c5ce0a2e1ff5d13109c3d1eac14bfdd",
            "Modified_By": {
                "name": "Patricia Boyle",
                "id": "1306462000000374001",
                "email": "p.boyle@abc.com"
            },
            "$review": null,
            "Skype_ID": "christopher-maclead",
            "Phone": "555-555-5555",
            "Lead_Class": null,
            "Email_Opt_Out": false,
            "Designation": "VP Accounting",
            "Modified_Time": "2021-10-05T14:37:26+05:30",
            "$converted_detail": {
                "deal": "1306462000000519017",
                "convert_date": "2021-10-05T20:07:26+05:30",
                "contact": "1306462000000396035",
                "converted_by": "1306462000000374001",
                "account": "1306462000000497010"
            },
            "Unsubscribed_Time": null,
            "Referred_By": null,
            "Mobile": "9400000001",
            "$orchestration": false,
            "$stop_processing": false,
            "Last_Name": "Maclead (Sample)",
            "$in_merge": false,
            "Lead_Source": "Cold Call",
            "Tag": [],
            "Fax": "1234123415",
            "$approval_state": "approved"
        }
    ],
    "info": {
        "call": false,
        "per_page": 200,
        "count": 1,
        "page": 1,
        "email": false,
        "more_records": false
    }
}