Get records from Zoho Books
Table of Contents
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: 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: 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:
|
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
"Contacts"
"53XXXXXX"
searchParam
"contact_name"
"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
"Estimates"
"53XXXXXX"
searchParam
encoded_name
"contact_name" "total_greater_than"
"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:
// 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"
}
Related Links
- Zoho Books API -> <Module> -> List <ModuleName>
- Common error codes can be viewed here