Records APIs

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.

Purpose

To get the list of available records from a module.

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}

module_api_name - The API name of the module

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

Request Method

GET

Scope

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

Possible module names	Possible operation types
leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom, and activities.	ALL - Full access to the record READ - Get records from the module

Parameters

Parameter Name	Data Type	Description	Possible Values
fields (optional)	String	To list all the module records with respect to fields	Multiple field API names, comma separated. For example: Last_Name,Email
sort_order (optional)	String	To sort the available list of records in either ascending or descending order	asc - ascending order desc - descending order
sort_by (optional)	String	To sort the available list of records based on the given field	Field API name Example: Email
converted (optional)	String	To get the list of converted records. Default value is false	true - get only converted records false - get only non-converted records both - get all records
approved (optional)	String	To get the list of approved records. Default value is true.	true - get only approved records false - get only records which are not approved both - get all records
page (optional)	Integer	To get the list of records from the respective pages. Default value for page is 1.	Positive Integer values only
per_page (optional)	Integer	To get the list of records available per page. Default value for page is 200.	Positive Integer values only
cvid (optional)	Integer	To get the list of records based on custom views	{custom_view_id}
territory_id (optional)	Integer	To get the list of records based on the territory	{territory_id}
include_child (optional)	Boolean	To include records from the child territories. True includes child territory records. False does not include child territory records. Default value is false.	true or false

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, 3 and 4) and per_page (100) parameter, the user can fetch all 400 records using 4 API calls.
Refer Response Structure for more details about the JSON keys, values, and their descriptions.

Request Headers

Header Name	Data Type	Description	Example
If-Modified-Since (optional)	DateTime (ISO 8601 format)	To get the list of recently modified records	2019-07-25T15:26:49+05:30

Note:

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.
To get the list of territories enabled for your organization, refer to 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.

Possible Errors

HTTP Status	Error Code	Message	Reason
400	INVALID_MODULE	The module name given seems to be invalid	Invalid module name or no tab permission, or the module could have been removed from the organized module
400	INVALID_MODULE	The given module is not supported in API	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.)
400	INVALID_MODULE	Territory is not supported for the given module	The given module is not territory-supported
403	NOT_SUPPORTED	This API is supported only for admin users	Only admin users can fetch records from the Notes module.

Sample Attributes

Attribute	Sample
Single Line	"Single_Line_1": "This is single line",
Multi Line	"Multi_Line_1": "This is the first line \n Now for the second Line",
Email	"Email_1": "p.boyle@zylker.com",
Phone	"Phone_1": "9900000000",
Picklist	"Picklist_1" : "In Progress",
Multi-Select Picklist	"Multi-Select_Picklist" : [ "Option_1", "Option_2", "Option_3" ],
Date	"Date_1": "2017-08-16",
Date/time	"Date_Time": "2017-08-16T14:32:23+05:30", Date_Time is in ISO8601 format and the time zone is the current user's time zone.
Number	"Number_1": 575,
Currency	"Currency_1": 250000,
Decimal	"Decimal_1": 250000.50,
Percent	""Percent_1": 25,
Long Integer	"Long_Integer_1": "250000000000000",
Checkbox	"Checkbox_1": false,
URL	URL_1": "https://www.zoho.com/crm",
Lookup	"Lookup" : { "name" : "James" "id" : "425248000000104001" },
Record Owner	"Owner": { "name" : "Patricia" "id": "425248000000104003" },
Layout	"Layout": { "name" : "Custom Layout 1" "id": "425248000000404433" },
Auto number	"Auto_Number_1": "LEAD44N", Where LEAD - Prefix, 44 - Assignment Number and N - Suffix.

Curl Java PHP Python Deluge Csharp

Sample Request


				curl "https://www.zohoapis.com/crm/v2/Accounts"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

Sample Response


				{
  "data": [
    {
      "Owner": {
        "name": "Patricia Boyle",
        "id": "554023000000235011"
      },
      "Ownership": "Private",
      "Description": null,
      "$currency_symbol": "Rs.",
      "Account_Type": "Partner",
      "Rating": null,
      "SIC_Code": null,
      "Shipping_State": null,
      "Website": null,
      "Product": null,
      "Employees": 200,
      "Last_Activity_Time": "2019-04-26T14:01:40+05:30",
      "Industry": "Education",
      "Record_Image": null,
      "Modified_By": {
        "name": "Patricia Boyle",
        "id": "554023000000235011"
      },
      "Account_Site": "Chennai - South",
      "$process_flow": false,
      "Phone": "555555555",
      "Billing_Country": null,
      "Account_Name": "Zylker",
      "id": "554023000000366005",
      "Account_Number": "0",
      "$approved": true,
      "Ticker_Symbol": null,
      "$approval": {
        "delegate": false,
        "approve": false,
        "reject": false,
        "resubmit": false
      },
      "Modified_Time": "2019-04-26T14:01:40+05:30",
      "Billing_Street": null,
      "Created_Time": "2019-03-22T15:28:27+05:30",
      "$editable": true,
      "Billing_Code": null,
      "Vendor": {
        "name": "MyVendor",
        "id": "554023000000310037"
      },
      "Territories": [
        "Chennai",
        "Chennai-South"
      ],
      "Parent_Account": {
        "name": "King",
        "id": "554023000000238121"
      },
      "Shipping_City": "Chennai",
      "Shipping_Country": null,
      "Shipping_Code": null,
      "Billing_City": "Chennai",
      "Billing_State": "Tamil Nadu",
      "Tag": [],
      "Created_By": {
        "name": "Patricia Boyle",
        "id": "554023000000235011"
      },
      "Fax": null,
      "Annual_Revenue": null,
      "Shipping_Street": null
    }
  ],
  "info": {
    "per_page": 200,
    "count": 1,
    "page": 1,
    "more_records": false
  }
}

Sample Request


				ZCRMModule module = ZCRMModule.getInstance("Products");
BulkAPIResponse response = module.getRecords(425476547854l, "Company",
CommonUtil.SortOrder.asc, 1, 4);// get Records with cvID, sortField,
sortOrder, startIndex and endIndex.
List<ZCRMRecord> records = (List<ZCRMRecord>)response.getData();

Sample Response


				{
    "data": [
       {
            "Zip_Code": null,
            "Long_Integer_1": null,
            "Annual_Revenue": 0,
            "Owner": {
                "id": "4108880000086001",
                "name": "Patricia Boyle"
            },
            "Date_2": null,
            "Created_Time": "2016-06-21T17:11:37+05:30",
            "Last_Activity_Time": "2016-06-21T17:11:37+05:30",
            "$full_name": "Jennifer Donelly",
            "Mobile": null,
            "Currency": "INR",
            "Pick_List_2": null,
            "Pick_List_1": null,
            "Date_Time_2": null,
            "Modified_Time": "2016-06-21T17:11:37+05:30",
            "Country": "United States",
            "Created_By": {
                "id": "4108880000006001",
                "name": "Patricia Boyle"
            },
            "Formula_1": 9,
            "Layout": {
                "id": "4108880000380037",
                "name": "Standard"
            },
            "Email": "jennifer@acme.com",
            "Secondary_Email": null,
            "Designation": null,
            "Industry": null,
            "Twitter": null,
            "Phone": null,
            "Street": null,
            "Modified_By": {
                "id": "4108880000086001",
                "name": "Patricia Boyle"
            },
            "Picks1": null,
            "Lead_Source": null,
            "$approved": true,
            "id": "4108880000610005",
            "$converted_detail": {},
            "Date_Testing": null,
            "Exchange_Rate": 1,
            "Auto_Number_1": "Test609Test",
            "Skype_ID": null,
            "Company": "AcmeInc",
            "Email_Opt_Out": false,
            "Decimal_1": null,
            "Description": null,
            "Website": null,
            "Fax": null,
            "Last_Name": "Donelly",
            "$converted": false,
            "City": "Cheni",
            "Lookup_1": null,
            "Lead_Status": null,
            "No_of_Employees": 0,
            "State": "Texas1",
            "$approval": {
                "approve": false,
                "reject": false,
                "delegate": false
            },
            "Date_Time": null,
            "Picks3": null,
            "Picks2": null
        }
    ],
    "info": {
        "per_page": 200,
        "count": 200,
        "page": 1,
        "more_records": true
    }
}

Sample Request


				$zcrmModuleIns = ZCRMModule::getInstance("Contacts");
$bulkAPIResponse=$zcrmModuleIns->getRecords();
$recordsArray = $bulkAPIResponse->getData(); // $recordsArray - array of ZCRMRecord instances

Sample Response


				{
    "data": [
       {
            "Zip_Code": null,
            "Long_Integer_1": null,
            "Annual_Revenue": 0,
            "Owner": {
                "id": "4108880000086001",
                "name": "Patricia Boyle"
            },
            "Date_2": null,
            "Created_Time": "2016-06-21T17:11:37+05:30",
            "Last_Activity_Time": "2016-06-21T17:11:37+05:30",
            "$full_name": "Jennifer Donelly",
            "Mobile": null,
            "Currency": "INR",
            "Pick_List_2": null,
            "Pick_List_1": null,
            "Date_Time_2": null,
            "Modified_Time": "2016-06-21T17:11:37+05:30",
            "Country": "United States",
            "Created_By": {
                "id": "4108880000006001",
                "name": "Patricia Boyle"
            },
            "Formula_1": 9,
            "Layout": {
                "id": "4108880000380037",
                "name": "Standard"
            },
            "Email": "jennifer@acme.com",
            "Secondary_Email": null,
            "Designation": null,
            "Industry": null,
            "Twitter": null,
            "Phone": null,
            "Street": null,
            "Modified_By": {
                "id": "4108880000086001",
                "name": "Patricia Boyle"
            },
            "Picks1": null,
            "Lead_Source": null,
            "$approved": true,
            "id": "4108880000610005",
            "$converted_detail": {},
            "Date_Testing": null,
            "Exchange_Rate": 1,
            "Auto_Number_1": "Test609Test",
            "Skype_ID": null,
            "Company": "AcmeInc",
            "Email_Opt_Out": false,
            "Decimal_1": null,
            "Description": null,
            "Website": null,
            "Fax": null,
            "Last_Name": "Donelly",
            "$converted": false,
            "City": "Cheni",
            "Lookup_1": null,
            "Lead_Status": null,
            "No_of_Employees": 0,
            "State": "Texas1",
            "$approval": {
                "approve": false,
                "reject": false,
                "delegate": false
            },
            "Date_Time": null,
            "Picks3": null,
            "Picks2": null
        }
    ],
    "info": {
        "per_page": 200,
        "count": 200,
        "page": 1,
        "more_records": true
    }
}

Sample Request


				def get_records(self):
        try:
            module_ins = ZCRMModule.get_instance('Invoices')  # module API Name
            resp = module_ins.get_records()
            print(resp.status_code)
            record_ins_arr = resp.data
            for record_ins in record_ins_arr:
                print(record_ins.entity_id)
                print(record_ins.owner.id)
                print(record_ins.created_by.id)
                print(record_ins.modified_by.id)
                print(record_ins.created_time)
                print(record_ins.modified_time)
                product_data = record_ins.field_data
                for key in product_data:
                    print(key + ":" + str(product_data[key]))
                print("\n\n")
        except ZCRMException as ex:
            print(ex.status_code)
            print(ex.error_message)
            print(ex.error_code)
            print(ex.error_details)
            print(ex.error_content)

Sample Request


				Syntax:
zoho.crm.getRecords(<module String>,<page Long>,<perPage Long>,<optionalDataMap Map>,<connectionName String>,<userAccess Boolean>);
mandatory : module

Sample Request:
resp = zoho.crm.getRecords("Leads",5,2,{"converted":"false"});

Sample Response


				{
    "data": [
       {
            "Zip_Code": null,
            "Long_Integer_1": null,
            "Annual_Revenue": 0,
            "Owner": {
                "id": "4108880000086001",
                "name": "Patricia Boyle"
            },
            "Date_2": null,
            "Created_Time": "2016-06-21T17:11:37+05:30",
            "Last_Activity_Time": "2016-06-21T17:11:37+05:30",
            "$full_name": "Jennifer Donelly",
            "Mobile": null,
            "Currency": "INR",
            "Pick_List_2": null,
            "Pick_List_1": null,
            "Date_Time_2": null,
            "Modified_Time": "2016-06-21T17:11:37+05:30",
            "Country": "United States",
            "Created_By": {
                "id": "4108880000006001",
                "name": "Patricia Boyle"
            },
            "Formula_1": 9,
            "Layout": {
                "id": "4108880000380037",
                "name": "Standard"
            },
            "Email": "jennifer@acme.com",
            "Secondary_Email": null,
            "Designation": null,
            "Industry": null,
            "Twitter": null,
            "Phone": null,
            "Street": null,
            "Modified_By": {
                "id": "4108880000086001",
                "name": "Patricia Boyle"
            },
            "Picks1": null,
            "Lead_Source": null,
            "$approved": true,
            "id": "4108880000610005",
            "$converted_detail": {},
            "Date_Testing": null,
            "Exchange_Rate": 1,
            "Auto_Number_1": "Test609Test",
            "Skype_ID": null,
            "Company": "AcmeInc",
            "Email_Opt_Out": false,
            "Decimal_1": null,
            "Description": null,
            "Website": null,
            "Fax": null,
            "Last_Name": "Donelly",
            "$converted": false,
            "City": "Cheni",
            "Lookup_1": null,
            "Lead_Status": null,
            "No_of_Employees": 0,
            "State": "Texas1",
            "$approval": {
                "approve": false,
                "reject": false,
                "delegate": false
            },
            "Date_Time": null,
            "Picks3": null,
            "Picks2": null
        }
    ],
    "info": {
        "per_page": 200,
        "count": 200,
        "page": 1,
        "more_records": true
    }
}

Sample Request


				ZCRMModule moduleIns = ZCRMModule.GetInstance("Leads"); //module api name
List<string> fields = new List<string> {"Last_Name","Company", "Email","id" }; //field api name
BulkAPIResponse<ZCRMRecord> response = moduleIns.GetRecords(3372164000000087503, "Company",CommonUtil.SortOrder.asc, 1, 4, fields);// get Records with cvId, sortByField, sortOrder, startIndex, endIndex and fieldApiNamelist.
List<ZCRMRecord> records = response.BulkData; //records - list of ZCRMRecord instance

Sample Response


				{
    "data": [
       {
            "Zip_Code": null,
            "Long_Integer_1": null,
            "Annual_Revenue": 0,
            "Owner": {
                "id": "4108880000086001",
                "name": "Patricia Boyle"
            },
            "Date_2": null,
            "Created_Time": "2016-06-21T17:11:37+05:30",
            "Last_Activity_Time": "2016-06-21T17:11:37+05:30",
            "$full_name": "Jennifer Donelly",
            "Mobile": null,
            "Currency": "INR",
            "Pick_List_2": null,
            "Pick_List_1": null,
            "Date_Time_2": null,
            "Modified_Time": "2016-06-21T17:11:37+05:30",
            "Country": "United States",
            "Created_By": {
                "id": "4108880000006001",
                "name": "Patricia Boyle"
            },
            "Formula_1": 9,
            "Layout": {
                "id": "4108880000380037",
                "name": "Standard"
            },
            "Email": "jennifer@acme.com",
            "Secondary_Email": null,
            "Designation": null,
            "Industry": null,
            "Twitter": null,
            "Phone": null,
            "Street": null,
            "Modified_By": {
                "id": "4108880000086001",
                "name": "Patricia Boyle"
            },
            "Picks1": null,
            "Lead_Source": null,
            "$approved": true,
            "id": "4108880000610005",
            "$converted_detail": {},
            "Date_Testing": null,
            "Exchange_Rate": 1,
            "Auto_Number_1": "Test609Test",
            "Skype_ID": null,
            "Company": "AcmeInc",
            "Email_Opt_Out": false,
            "Decimal_1": null,
            "Description": null,
            "Website": null,
            "Fax": null,
            "Last_Name": "Donelly",
            "$converted": false,
            "City": "Cheni",
            "Lookup_1": null,
            "Lead_Status": null,
            "No_of_Employees": 0,
            "State": "Texas1",
            "$approval": {
                "approve": false,
                "reject": false,
                "delegate": false
            },
            "Date_Time": null,
            "Picks3": null,
            "Picks2": null
        }
    ],
    "info": {
        "per_page": 200,
        "count": 200,
        "page": 1,
        "more_records": true
    }
}