Create record

Create records in Zoho Books

Overview

This task is used to create a record in Zoho Books.

Syntax

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

where,

ParameterData typeDescription

<variable> 

KEY-VALUE

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

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 account in which the record will be created.

<data_map>

KEY-VALUE

Input map with key as Zoho Books field's name and the required value.

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

<connection>*

(optional)

TEXT

specifies the name of the Zoho Books connection.

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

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);

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

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);

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

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

    Share this post : FacebookTwitter

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

    Write to us: support@zohodeluge.com