Create records in Zoho Books

Table of Contents Up

Note:

  • Each time the zoho.books.createRecord 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.createRecord 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 create a record in Zoho Books.

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

Syntax

<variable> = zoho.books.createRecord(<module_name>, <org_ID>, <data_map>, <connection>);

where,

ParameterData typeDescription
<variable> KEY-VALUEis the variable which will hold the response returned by Zoho Books
<module_name> TEXT

specifies the Zoho Books' module in which the record will be created.

The applicable modules can be found in the "Request Example" section in Zoho Books API -> <Module> -> Create <ModuleName> 

<org_ID>TEXTspecifies the organization ID of the account in which the record will be created.
<data_map>KEY-VALUEInput map with key as Zoho Books field's name and the required value.

To learn about the mandatory fields, click here and navigate to <Module> -> Create <ModuleName>

<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> -> Create <ModuleName>.
  • Refer to this post for the list of Zoho services that support the connections page.
  • Learn more about connections

Examples

1) Let's say we have a Zoho Creator form containing a field called Customer_ID, and a subform called Products. The subform contains fields item_id, name, rate, and quantity. On submission of this form, an invoice must be created in Zoho Books with the details specified in the subform. We can achieve this using the following snippet:

listVar = List();

​//iterating each row in the subform
for each  line in Products
{
  mapVar = map();
  mapVar.put("item_id", line.item_id);
  mapVar.put("name", line.name);
  mapVar.put("rate", line.rate);
  mapVar.put("quantity", line.quantity);
  listVar.add(mapVar);
}
values = map();
values.put("customer_id", input.Customer_ID);
values.put("line_items", listVar);
response = zoho.books.createRecord("Invoices", "66XXXXX66", values, "books_connection");

where,

listVar
is the LIST variable that holds the list of key value pairs for the line items in the invoice
 mapVar
 values
are the MAP variables which hold key value pairs
 "item_id"
 "name"
 "rate"
 "quantity"
 "customer_id"
 "line_items"
are the TEXT that represents the label name of the field specified in Zoho Books' API. Customer ID and Item ID can be viewed in the URL in Zoho Books account when you click on a record in Customers or Items modules respectively.
"Invoices"
is the TEXT that represents the module in which the record needs to be created
"66XXXXX66"
is the TEXT that represents the organization ID of the Zoho Books account in which the record needs to be created
"books_connection"
is the TEXT that represents Zoho Books connection name

2) The following script creates a new record in the Zoho Books module - Contacts with the specified values.

 contactMap=map();
 contactMap.put("contact_name","Bowman and Co 3");
 contactMap.put("company_name","Bowman and Co 3");
 contactMap.put("gst_no","07CQZCD1111I4Z7");
 contactMap.put("gst_treatment","business_gst");
 contactMap.put("first_name","Will");
 contactMap.put("last_name","Smith");
 contactMap.put("contact_type","vendor");
 contactMap.put("pan_no","ABCDE1234F");
 contactMap.put("email","willsmith@bowmanfurniture.com");
 contactMap.put("phone","+1-925-921-XXXX");
 response= zoho.books.createRecord("Contacts", "5379XXXX", contactMap, "books_connection");

where,

contactMap
is the KEY-VALUE variable that holds the values of the new record that needs to be created
 "contact_name"
 "company_name"
 "gst_no"
 "gst_treatment"
 "tax_id"
 "first_name"
 "last_name"
 "email"
 "phone"
are the TEXT that represents the label name of the field specified in Zoho Books' API
"Contacts"
is the TEXT that represents the module in which the record needs to be created
"5379XXXX"
is the TEXT that represents the organization ID of the Zoho Books account in which the record needs to be created
"books_connection"
is the TEXT that represents Zoho Books connection name

Sample Response

Success Response

  • The following is a sample success response:

    {  
       "code":0,
       "contact":{  
          "is_crm_customer":false,
          "addresses":[  

          ],
          "notes":"",
          "documents":[  

          ],
          "owner_id":"",
          "is_linked_with_zohocrm":false,
          "is_client_review_settings_enabled":false,
          "pan_no":"ABCDE1234F",
          "billing_address":{  
             "zip":"",
             "country":"",
             "address":"",
             "city":"",
             "phone":"",
             "address_id":"14606XXXXXXXXXXXX",
             "attention":"",
             "street2":"",
             "state":"",
             "state_code":"",
             "fax":""
          },
          "default_templates":{  
             "invoice_email_template_id":"",
             "salesorder_email_template_id":"",
             "salesorder_template_id":"",
             "creditnote_email_template_id":"",
             "creditnote_template_name":"",
             "paymentthankyou_email_template_name":"",
             "estimate_template_id":"",
             "paymentthankyou_template_id":"",
             "salesorder_email_template_name":"",
             "salesorder_template_name":"",
             "invoice_email_template_name":"",
             "creditnote_email_template_name":"",
             "invoice_template_id":"",
             "paymentthankyou_email_template_id":"",
             "invoice_template_name":"",
             "estimate_template_name":"",
             "estimate_email_template_id":"",
             "creditnote_template_id":"",
             "paymentthankyou_template_name":"",
             "estimate_email_template_name":""
          },
          "source":"api",
          "outstanding_receivable_amount_bcy":0.0,
          "language_code":"",
          "twitter":"",
          "unused_credits_receivable_amount_bcy":0.0,
          "gst_no":"07CQZCD1111I4Z7",
          "tax_reg_no":"ABCDE1234F",
          "contact_category":"business_gst",
          "associated_with_square":false,
          "place_of_contact":"DL",
          "contact_persons":[  

          ],
          "pricebook_id":"",
          "outstanding_receivable_amount":0.0,
          "gst_treatment":"business_gst",
          "created_time":"2017-11-27T14:51:44+0530",
          "owner_name":"",
          "custom_fields":[  

          ],
          "vat_reg_no":"ABCDE1234F",
          "unused_credits_receivable_amount":0.0,
          "has_transaction":false,
          "outstanding_payable_amount_bcy":0.0,
          "tax_id":"14606XXXXXXXXXXXX",
          "pricebook_name":"",
          "price_precision":2,
          "tags":[  

          ],
          "primary_contact_id":"",
          "country_code":"",
          "checks":[  

          ],
          "unused_credits_payable_amount_bcy":0.0,
          "company_name":"Bowman and Co 3",
          "tax_treatment":"business_gst",
          "crm_owner_id":"",
          "status":"active",
          "cards":[  

          ],
          "zcrm_vendor_id":"",
          "contact_id":"14606XXXXXXXXXXXX",
          "payment_terms":0,
          "currency_code":"INR",
          "outstanding_payable_amount":0.0,
          "contact_type":"vendor",
          "unused_credits_payable_amount":0.0,
          "shipping_address":{  
             "zip":"",
             "country":"",
             "address":"",
             "city":"",
             "phone":"",
             "address_id":"14606XXXXXXXXXXXX",
             "attention":"",
             "street2":"",
             "state":"",
             "state_code":"",
             "fax":""
          },
          "contact_name":"Bowman and Co 3",
          "website":"",
          "is_client_review_asked":false,
          "last_modified_time":"2017-11-27T14:51:44+0530",
          "language_code_formatted":"",
          "currency_symbol":"Rs.",
          "ach_supported":false,
          "facebook":"",
          "tax_name":"GST12",
          "vendor_portal_url":"",
          "unused_retainer_payments":0.0,
          "contact_salutation":"",
          "tax_percentage":12.0,
          "bank_accounts":[  

          ],
          "currency_id":"14606XXXXXXXXXXXX",
          "payment_terms_label":"Due On Receipt",
          "payment_reminder_enabled":true
       },
       "instrumentation":{  
          "query_execution_time":123,
          "response_write_time":153,
          "page_context_write_time":0,
          "request_handling_time":506
       },
       "message":"The contact has been added."
    }

To get the ID of the newly created record, execute the following script:

<variable> = <response_variable>.get("<module_name>").get("<module_name>_id">) ;
// example for <module_name> is contact and example for <module_name>_id is contact_id

Failure Response

The failure response returned due to incorrect organization ID is of the following format:

          {  
             "code":6041,
             "message":"This user is not associated with the CompanyID/CompanyName:537XX."
         }

Related Links