Fetch records

Get records from Zoho Books

Overview

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

Syntax

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

where,

ParamsData TypeDescription

<variable>

KEY-VALUE

specifies the variabe which will return the response returned by Zoho Books which contains the list of records, number of fetched records and related information.

<module_name>

TEXT

specifies the Zoho Books module from which the records will be fetched.

Following are the applicable modules.

RecurringInvoicesItemsInvoicesEstimatesSalesordersContactsBills
CustomerPaymentsJournals

Projects

(not applicable in Zoho Creator)

ExpensesPurchaseorders

CreditNotes

(not applicable in Zoho Creator)

-

<org_ID>

TEXT

specifies the organization ID of the Zoho Books account, from where the records will be fetched.

<search>

(optional)

KEY-VALUE

(data type applicable for all Zoho services except Zoho Creator)

(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.

When the param is used as a string:
Click here and go to <moduleName> -> list <moduleName> -> filter_by for more information on the applicable values for this param.

Note: The search values must be encoded.

<connection>*

(optional)

TEXT

specifies the name of the Zoho Books connection.

*Note: This param is not applicable in Zoho Creator.

Example : Fetch record from Zoho Books

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

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

where,

response
is the variable which will hold the KEY-VALUE response returned form 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

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 returned due to invalid search parameter is of the following format:

     {
     "code":2,
     "message":"Invalid value passed for filter_by"
     }

Related Links

Share this post : FacebookTwitter

Still can't find what you're looking for?

Write to us: support@zohodeluge.com