Get records from Zoho Books

Overview
Syntax
Example
Sample Response
Related Links

Note:

Each time the zoho.books.getRecords integration task is executed, it triggers an API request in the back-end. This call is deducted from the external calls limit available for the service from which the task is executed, based on your pricing plan.
Only actual executions that receive a response (whether success or failure) are counted, not the number of times the task appears in the script. For example, if zoho.books.getRecords integration task is placed inside a for each task that iterates five times, the number of external calls consumed will be five, even though the task appears only once in the script.

Overview

This task is used to fetch records from a specified module in Zoho Books.

This task is based on Zoho Books API -> <Module> -> List <ModuleName>.

Syntax

<variable> = zoho.books.getRecords(<module_name>, <org_ID>, <search>, <connection>);

Params	Data Type	Description
<variable>	KEY-VALUE	Variable to hold the response returned by Zoho Books.
<module_name>	TEXT	specifies the Zoho Books module from which the records will be fetched. The applicable module names can be found in the "Request Example" section in Zoho Books API -> <Module> -> List <ModuleName>
<org_ID>	TEXT	specifies the organization ID of the Zoho Books account, from where the records will be fetched.
<search>	KEY-VALUE (or) TEXT	specifies the values based on which the records will be filtered. When the param is used as key-value: Click here and go to <moduleName> -> list <moduleName>. All query params listed there are applicable as keys with the required values. The values are not case-sensitive. Note: Key-value data type is applicable for all Zoho services except Zoho Creator. When the param is used as a text: Click here and go to <moduleName> -> list <moduleName>. All query params listed there are applicable as keys with the required values in format <key>=<value>. Multiple criteria can be specified in the format: <key>=<value>&<key>=<value>. The values must be encoded if they contain spaces. Note: You can specify an empty string or an empty map for this param, in which case all the records will be fetched
<connection>	TEXT	is the name of the Zoho Books connection Note: In view of stopping new authtoken generation, a Zoho OAuth connection with appropriate scopes is mandatory for new integration tasks (created after the deadline specified in the post) to work as expected. Existing integration tasks will continue to work with or without the connections parameter unless the authtoken is manually deleted from accounts. Add relevant scopes as mentioned in Zoho Books API -> <Module> -> List <ModuleName>. Refer to this post for the list of Zoho services that support the connections page. Learn more about connections

Example 1: Fetch records from Zoho Books using KEY-VALUE search parameter (Applicable for all services except Zoho Creator)

The following script fetches records from the Zoho Books module - Contacts which contains the contact_name - Will.

 searchParam = {"contact_name":"Will"}; 
 response = zoho.books.getRecords("Contacts", "53XXXXXX", searchParam, "books_connection");

where,

response

is the variable which will hold the KEY-VALUE response returned from Zoho Books. It represents the values of the fetched records.

"Contacts"

is the TEXT that represents the module from which records will be fetched.

"53XXXXXX"

is the TEXT that represents the organization ID of the Zoho Books account from which the records will be fetched.

searchParam

is the KEY-VALUE variable that holds the search parameter

"contact_name"

is the TEXT that represents the query parameter specified in Zoho books API

"books_connection"

is the TEXT that represents Zoho Books connection

Example 2: Fetch records from Zoho Books using TEXT search parameter (Applicable for all services)

The following script fetches records from the Zoho Books module - Estimate if the value against the field contact_name is Shawn Smith and the total estimate amount exceeds 2000.

 encoded_name = encodeUrl("Shawn Smith");
 response = zoho.books.getRecords("Estimates", "53XXXXXX", "contact_name="+ encoded_name+ "&total_greater_than=20000", "books_connection");
 info response;

where:

response

is the variable that will hold the KEY-VALUE response returned from Zoho Books. It represents the values of the fetched records.

"Estimates"

is the TEXT that represents the module from which records will be fetched.

"53XXXXXX"

is the TEXT that represents the organization ID of the Zoho Books account from which the records will be fetched.

searchParam

is the KEY-VALUE variable that holds the search parameter

encoded_name

is the TEXT variable that holds the encoded contact name

"contact_name" 
"total_greater_than"

is the TEXT variable that represents the query parameters specified in Zoho books API

"books_connection"

is the TEXT that represents the Zoho Books connection

Sample Response

The following is a sample success response:
  {
  "code": 0,
  "message": "success",
  "contacts": [
  {
  "contact_id": "XXXXXXXXXX05023",
  "contact_name": "Will Smith",
  "customer_name": "1",
  "vendor_name": "1",
  "company_name": "",
  "website": "",
  "language_code": "",
  "language_code_formatted": "",
  "contact_type": "customer",
  "contact_type_formatted": "Customer",
  "status": "active",
  "customer_sub_type": "business",
  "source": "zoho_crm",
  "is_linked_with_zohocrm": true,
  "payment_terms": 0,
  "payment_terms_label": "Due On Receipt",
  "currency_id": "XXXXXXXXXX00099",
  "twitter": "",
  "facebook": "",
  "currency_code": "INR",
  "outstanding_receivable_amount": 0.0,
  "outstanding_receivable_amount_bcy": 0.0,
  "outstanding_payable_amount": 0.0,
  "outstanding_payable_amount_bcy": 0.0,
  "unused_credits_receivable_amount": 0.0,
  "unused_credits_payable_amount": 0.0,
  "first_name": "",
  "last_name": "1",
  "email": "",
  "phone": "",
  "mobile": "",
  "created_time": "2018-12-11T15:45:00+0530",
  "created_time_formatted": "11/12/2018",
  "last_modified_time": "2018-12-11T15:45:04+0530",
  "last_modified_time_formatted": "11/12/2018",
  "custom_fields": [
  ],
  "ach_supported": false,
  "has_attachment": false
  }
  ],
  "page_context": {
  "page": 1,
  "per_page": 200,
  "has_more_page": false,
  "report_name": "Contacts",
  "applied_filter": "Status.All",
  "sort_column": "contact_name",
  "search_criteria": [
  {
  "column_name": "contact_name",
  "search_text": "Will Smith",
  "comparator": "equal"
  }
  ]
  }
  }

To fetch the IDs of the records, execute the following snippet:

var = <response_variable>.get("<module_name>");
// example for <module_name> is contacts
for each var1 in var
{
info var1.toMap().get("<module_name>_id");
// example for <module_name>_id is contact_id
}

Failure Response

The failure response returned due to invalid organization ID is of the following format:
{
"code":6041,
"message":"This user is not associated with the CompanyID/CompanyName:63XX."
}
The failure response returned due to invalid search parameter is of the following format:
{
"code":2,
"message":"Invalid value passed for filter_by"
}