Insert Records API
Purpose
To add new entities to a module.
Endpoints
Request Details
Request URL
https://www.zohoapis.com/bigin/v1/{module_api_name}
Scope
scope=ZohoBigin.modules.ALL
(or)
scope=ZohoBigin.modules.{module_name}.{operation_type}
Possible module names
Accounts(companies in Bigin), contacts, deals, tasks, events, calls, products and notes
Possible operation types
ALL - Full access to the record
WRITE - Edit records in the module
CREATE - Create records in the module
To insert a single record, send only one JSON object in the input with the necessary keys and values.
An error is thrown if the field value length is more than the maximum length defined for that field.
If an API is used inside a Function and the field value length exceeds the limit, then that function receives an error response from the API. For ex: If the max length for a "Text field" is defined as 10, then value given for it in API cannot be "12345678901", as it has 11 characters.
Duplicates are checked for every insert record API call based on unique fields.
A maximum of 100 records can be inserted per API call.
You must use only Field API names in the input. You can obtain the field API names from:
Fields metadata API (the value for the key “api_name” for every field).
The trigger input is workflow. If "trigger" is not mentioned, the workflows related to the API will get executed. Enter the trigger value as [] to not execute the workflows.
Refer Response Structure for more details about the JSON keys, values, and their descriptions. You can also use the sample response of each module as the input when you insert, update, or upsert a record in that corresponding module.
Sample Request
Copiedcurl "https://www.zohoapis.com/bigin/v1/Contacts"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@newcontact.json"
-X POST
CopiedList<ZCRMRecord> records = new ArrayList<>();
ZCRMRecord record1 = new ZCRMRecord("Products"); //module api name
ZCRMUser owner = ZCRMUser.getInstance(554023000000235011);// user id
record1.setOwner(owner);
record1.setFieldValue("Product_Name", "Product_New");// field api name with its value
ZCRMRecord record2 = new ZCRMRecord("Products"); //module api name
ZCRMUser owner1 = ZCRMUser.getInstance(554023000000235011);
record2.setOwner(owner1);
record2.setFieldValue("Product_Name", "Product_New2");// field api name with its value
records.add(record1);
records.add(record2);
ZCRMModule module = ZCRMModule.getInstance("Products"); //module api name
BulkAPIResponse response = module.createRecords(records);
List<ZCRMRecord> insertedRecords = (List<ZCRMRecord>) response.getData();
List<BulkAPIResponse.EntityResponse> entityResponses =
response.getEntityResponses();// to check the status of the request
String rec1Status = entityResponses.get(0).getStatus();//check status of record1
String rec2Status = entityResponses.get(1).getStatus();//check
Copied$moduleIns=ZCRMRestClient::getInstance()->getModuleInstance("Invoices"); //to get the instance of the module
$records=array();
$record=ZCRMRecord::getInstance("Invoices",null); //To get ZCRMRecord instance
$record->setFieldValue("Subject","Invoice1"); //This function use to set FieldApiName and value similar to all other FieldApis and Custom field
$record->setFieldValue("Account_Name","554023000000366005"); //This function is for Invoices module
/** Following methods are being used only by Inventory modules **/
$lineItem=ZCRMInventoryLineItem::getInstance(null); //To get ZCRMInventoryLineItem instance
$lineItem->setDescription("Product_description"); //To set line item description
$lineItem ->setDiscount(5); //To set line item discount
$lineItem->setListPrice(100); //To set line item list price
$taxInstance1=ZCRMTax::getInstance("VAT"); //To get ZCRMTax instance
$taxInstance1->setPercentage(2); //To set tax percentage
$taxInstance1->setValue(50); //To set tax value
$lineItem->addLineTax($taxInstance1); //To set line tax to line item
$taxInstance1=ZCRMTax::getInstance("Sales_Tax"); //to get the tax instance
$taxInstance1->setPercentage(12); //to set the tax percentage
$taxInstance1->setValue(50); //to set the tax value
$lineItem->addLineTax($taxInstance1); //to add the tax to line item
$lineItem->setProduct(ZCRMRecord::getInstance("Price_Books",554023000000504001)); //To set product to line item
$lineItem->setQuantity(100); //To set product quantity to this line item
$record->addLineItem($lineItem); //to add the line item to the record
array_push($records, $record); //pushing the record to the array
$responseIn=$moduleIns->createRecords($records); //updating the records
foreach($responseIn->getEntityResponses() as $responseIns){
echo "HTTP Status Code:".$responseIn->getHttpStatusCode(); //To get http response code
echo "Status:".$responseIns->getStatus(); //To get response status
echo "Message:".$responseIns->getMessage(); //To get response message
echo "Code:".$responseIns->getCode(); //To get status code
echo "Details:".json_encode($responseIns->getDetails());
}
Copieddef create_records(self):
try:
record_ins_list = list()
for i in range(0, 2):
record = zcrmsdk.ZCRMRecord.get_instance('Invoices') # Module API Name
record.set_field_value('Subject', 'Invoice' + str(
i)) # This method use to set FieldApiName and value similar to all other FieldApis and Custom field
record.set_field_value('Account_Name', 'Zylker')
record.set_field_value('Price_Book_Name', 'Price_Book1')
record.set_field_value('Pricing_Model', 'Flat')
record.set_field_value('Event_Title', 'Title')
record.set_field_value('Start_DateTime', '2018-09-04T15:52:21+05:30')
record.set_field_value('End_DateTime', '2019-01-04T15:52:21+05:30')
record.set_field_value('Product_Name', 'Product_New')
user = zcrmsdk.ZCRMUser.get_instance(680341392, 'Patricia Boyle') # user id and user name
record.set_field_value('Owner', user)
# Following methods are being used only by Inventory modules
taxIns = zcrmsdk.ZCRMTax.get_instance("Vat")
record.tax_list.append(taxIns)
pricing = zcrmsdk.ZCRMPriceBookPricing(None)
pricing.to_range = 5
pricing.from_range = 1
pricing.discount = 0
record.price_details.append(pricing)
pricing = zcrmsdk.ZCRMPriceBookPricing(None)
pricing.to_range = 11
pricing.from_range = 6
pricing.discount = 1
record.price_details.append(pricing)
pricing = zcrmsdk.ZCRMPriceBookPricing(None)
pricing.to_range = 17
pricing.from_range = 12
pricing.discount = 2
record.price_details.append(pricing)
# participants = zcrmsdk.ZCRMEventParticipant(3477061000000,'contact') # Contacts record id and participant type
# record.participants.append(participants)
# participants = zcrmsdk.ZCRMEventParticipant('usermail@domain.com', 'email')
# participants.email = 'usermail@domain.com'
# participants.name = 'username'
# participants.is_invited = 'true'
# record.participants.append(participants)
line_item = zcrmsdk.ZCRMInventoryLineItem.get_instance(
zcrmsdk.ZCRMRecord.get_instance('Products', 347706100)) # module api name and record id
line_item.discount = 10
line_item.list_price = 8
line_item.description = 'Product Description'
line_item.quantity = 100
line_item.tax_amount = 2.5
taxIns = zcrmsdk.ZCRMTax.get_instance("Vat")
taxIns.percentage = 5
line_item.line_tax.append(taxIns)
record.add_line_item(line_item)
line_tax = []
line_tax_row1 = {}
line_tax_row1['percentage'] = 12.5
line_tax_row1['name'] = 'Sales Tax'
line_tax.append(line_tax_row1)
line_tax_row2 = {}
line_tax_row2['percentage'] = 8.5
line_tax_row2['name'] = 'Common Tax'
line_tax.append(line_tax_row2)
record.set_field_value('$line_tax', line_tax)
record_ins_list.append(record)
resp = zcrmsdk.ZCRMModule.get_instance('Invoices').create_records(record_ins_list)
print(resp.status_code)
entity_responses = resp.bulk_entity_response
for entity_response in entity_responses:
print(entity_response.details)
print(entity_response.status)
print(entity_response.message)
print(entity_response.data.entity_id)
print(entity_response.data.created_by.id)
print(entity_response.data.created_time)
print(entity_response.data.modified_by.id)
print("\n\n")
except zcrmsdk.ZCRMException as ex:
print(ex.status_code)
print(ex.error_message)
print(ex.error_code)
print(ex.error_details)
print(ex.error_content)
CopiedSyntax:
zoho.crm.bulkCreate(<module String>,<dataList List>,<optionalDataMap Map>,<connectionName String>,<userAccess Boolean>);
mandatory : module,dataList
Sample Request:
resp = zoho.crm.bulkCreate("Price_Books", [{"Owner": {"id": "7000000031553"},"Active": true,"Pricing_Details": [{"to_range": 5,"discount": 0,"from_range": 1},{"to_range": 11,"discount": 1,"from_range": 6},{"to_range": 17,"discount": 2,"from_range": 12},{"to_range": 23,"discount": 3,"from_range": 18},{"to_range": 29,"discount": 4,"from_range": 24}],"Pricing_Model": "Differential","Description": "Design your own layouts that align your business processes precisely. Assign them to profiles appropriately.","Price_Book_Name": "Price_Book_Name oops1"},{"Owner": {"id": "7000000031553"},"Active": true,"Pricing_Details": [{"to_range": 5,"discount": 0,"from_range": 1},{"to_range": 11,"discount": 1,"from_range": 6},{"to_range": 17,"discount": 2,"from_range": 12},{"to_range": 23,"discount": 3,"from_range": 18},{"to_range": 29,"discount": 4,"from_range": 24}],"Pricing_Model": "Differential","Description": "Design your own layouts that align your business processes precisely. Assign them to profiles appropriately.","Price_Book_Name": "Price_Book_Name oops2"}]);
Copiedpublic void CreateRecords()
{
List<ZCRMRecord> listRecord = new List<ZCRMRecord>();
ZCRMRecord record;
record = ZCRMRecord.GetInstance("Invoices", null); //To get ZCRMRecord instance
record.SetFieldValue("Subject", "Invoice4"); //This method use to set FieldApiName and value similar to all other FieldApis and Custom field
record.SetFieldValue("Account_Name", 3372164000001855101);
record.SetFieldValue("Company", "KK");
record.SetFieldValue("Last_Name", "User");
record.SetFieldValue("Customfield", "CustomFieldValue");
record.SetFieldValue("Price_Book_Name", "Price_Book_Name");
//Following methods are used to upload a file to a field
List<ZCRMFiles> fileObjects = new List<ZCRMFiles>();
ZCRMFiles file = ZCRMFiles.GetInstance("aexxxxxxxxxx732e26505e22e", null);
fileObjects.Add(file);
file = ZCRMFiles.GetInstance("aexxxxxxxxxx732e26505e22e", null);
fileObjects.Add(file);
record.SetFieldValue("File_Upload", fileObjects);
/** Following methods are being used only by Inventory modules */
ZCRMPriceBookPricing pricing;
pricing = new ZCRMPriceBookPricing
{
ToRange = 5,
FromRange = 1,
Discount = 0
};
record.AddPriceDetail(pricing);
pricing = new ZCRMPriceBookPricing
{
ToRange = 11,
FromRange = 6,
Discount = 1
};
record.AddPriceDetail(pricing);
pricing = new ZCRMPriceBookPricing
{
ToRange = 17,
FromRange = 12,
Discount = 2
};
record.AddPriceDetail(pricing);
pricing = new ZCRMPriceBookPricing
{
ToRange = 23,
FromRange = 18,
Discount = 3
};
record.AddPriceDetail(pricing);
record.SetFieldValue("Pricing_Model", "Flat");
ZCRMTax linetax;
linetax = ZCRMTax.GetInstance("Sales Tax");
linetax.Percentage = 12.5;
record.AddTax(linetax);
ZCRMRecord product = ZCRMRecord.GetInstance("Products", 3372164000000190001); // product instance
ZCRMInventoryLineItem lineItem = new ZCRMInventoryLineItem(product); //To get ZCRMInventoryLineItem instance
lineItem.Description = "Product_description"; //To set line item description
lineItem.Discount = 5; //To set line item discount
lineItem.ListPrice = 100; //To set line item list price
ZCRMTax taxInstance1 = ZCRMTax.GetInstance("Sales Tax"); //To get ZCRMTax instance
taxInstance1.Percentage = 2; //To set tax percentage
taxInstance1.Value = 50; //To set tax value
lineItem.AddLineTax(taxInstance1); //To set line tax to line item
taxInstance1 = ZCRMTax.GetInstance("Vat");
taxInstance1.Percentage = 12;
taxInstance1.Value = 50;
lineItem.AddLineTax(taxInstance1);
lineItem.Quantity = 100; //To set product quantity to this line item
record.AddLineItem(lineItem); //The line item set to the record object
/** End Inventory **/
listRecord.Add(record);
record = ZCRMRecord.GetInstance("Invoices", null); //To get ZCRMRecord instance
record.SetFieldValue("Subject", "Invoice4"); //This method use to set FieldApiName and value similar to all other FieldApis and Custom field
record.SetFieldValue("Account_Name", 3372164000001855101);
record.SetFieldValue("Company", "KK");
record.SetFieldValue("Last_Name", "User");
record.SetFieldValue("Customfield", "CustomFieldValue");
record.SetFieldValue("Price_Book_Name", "Price_Book_Name1");
/** Following methods are being used only by Inventory modules */
ZCRMPriceBookPricing pricing1;
pricing1 = new ZCRMPriceBookPricing
{
ToRange = 5,
FromRange = 1,
Discount = 0
};
record.AddPriceDetail(pricing1);
pricing1 = new ZCRMPriceBookPricing
{
ToRange = 11,
FromRange = 6,
Discount = 1
};
record.AddPriceDetail(pricing1);
pricing1 = new ZCRMPriceBookPricing
{
ToRange = 17,
FromRange = 12,
Discount = 2
};
record.AddPriceDetail(pricing1);
pricing1 = new ZCRMPriceBookPricing
{
ToRange = 23,
FromRange = 18,
Discount = 3
};
record.AddPriceDetail(pricing1);
record.SetFieldValue("Pricing_Model", "Flat");
linetax = ZCRMTax.GetInstance("Sales Tax");
linetax.Percentage = 12.5;
record.AddTax(linetax);
ZCRMRecord product1 = ZCRMRecord.GetInstance("Products", 3372164000000190001); // product instance
ZCRMInventoryLineItem lineItem1 = new ZCRMInventoryLineItem(product1)
{
Description = "Product_description", //To set line item description
Discount = 5, //To set line item discount
ListPrice = 100 //To set line item list price
}; //To get ZCRMInventoryLineItem instance
lineItem1.DiscountPercentage = 10;
ZCRMTax taxInstance11 = ZCRMTax.GetInstance("Sales Tax"); //To get ZCRMTax instance
taxInstance11.Percentage = 2; //To set tax percentage
taxInstance11.Value = 50; //To set tax value
lineItem1.AddLineTax(taxInstance11); //To set line tax to line item
taxInstance11 = ZCRMTax.GetInstance("Vat");
taxInstance11.Percentage = 12;
taxInstance11.Value = 50;
lineItem1.AddLineTax(taxInstance11);
lineItem1.Quantity = 100; //To set product quantity to this line item
record.AddLineItem(lineItem1); //The line item set to the record object
/** End Inventory **/
listRecord.Add(record);
ZCRMModule moduleIns = ZCRMModule.GetInstance("Invoices");
List<string> trigger = new List<string>() { "workflow", "approval", "blueprint" };
string larID = "3477053013";
BulkAPIResponse<ZCRMRecord> responseIns = moduleIns.CreateRecords(listRecord, trigger, larID); //To call the create record method
Console.WriteLine("HTTP Status Code:"+responseIns.HttpStatusCode); //To get create record http response code
foreach (EntityResponse response in responseIns.BulkEntitiesResponse)
{
Console.WriteLine("Status:" + response.Status); //To get create record response status
Console.WriteLine("Message:" + response.Message); //To get create record response message
Console.WriteLine("Details:" + response.ResponseJSON); //To get create record response details
ZCRMRecord record1 = (ZCRMRecord)response.Data;
Console.WriteLine(record1.EntityId); //To get inserted record id
Console.WriteLine(record1.CreatedTime);
Console.WriteLine(record1.ModifiedTime);
ZCRMUser CreatedBy = record1.CreatedBy;
if(CreatedBy != null)
{
Console.WriteLine(CreatedBy.Id);
Console.WriteLine(CreatedBy.FullName);
}
ZCRMUser ModifiedBy = record1.ModifiedBy;
if (ModifiedBy != null)
{
Console.WriteLine(ModifiedBy.Id);
Console.WriteLine(ModifiedBy.FullName);
}
}
}
In the request, "@newcontact.json" contains the sample input data.
System-defined mandatory fields for each module
While inserting records there are a few system-defined mandatory fields that you need to mention. Inorder to successfully insert records in Bigin, make sure you enter user-defined mandatory fields too.
- Contacts
"Last_Name" - Single Line
- Companies
"Account_Name" - Single Line
- Deals
"Deal_Name"- Single Line
"Stage" - Picklist"Closing_Date"-Date
- Tasks
"Subject" - Multi Line
- Calls
"Subject" - Multi Line
"Call_Type" - Picklist
"Call_Start_Time" - Date/Time
"Call_Duration" - Single Line - Events
"Event_Title"- Single Line
"Start_DateTime" - Date/Time
"End_DateTime" - Date/Time - Products
"Product_Name" - Single Line
Sample Attributes
The following table gives you specific details about each field type in Bigin and their limitations. The JSON type and the data type of the field-types are extracted from fields meta data API.
- Single Linestring
Accepts up to 255 characters, and alphanumeric and special characters.
Example:"Last_Name": "Mike O'Leary" - Multi Linestring
Small - accepts up to 2000 characters.
Large - accepts up to 32000 characters.
You will not be able to use this field to create custom views, reports or other filters. Accepts alphanumeric and special characters.
Example:"Multi_Line_1": "This is the first line \n Now for the second Line" - Emailstring
Accepts valid email IDs.
Example:"Email_1": "p.boyle@zylker.com" - Phonestring
Accepts up to 30 characters. This limit may vary based on the value configured in 'Number of characters allowed' in the properties pop-up of the field, in UI.
Accepts only numeric characters and '+' (to add extensions). The regex pattern in Bigin to validate this field's value is "[0-9a-zA-Z!#;%\\*\\^\\(\\)=\\{\\}\\[\\]\\?`~_\\-\\.\\$@\\?\\,\\:\\'\\/\\!\\P{InBasicLatin}\\|\\\\\\s\\+]+"
Example:"Phone_1": "9900000000" - Pickliststring
You can either pass an existing pick list value or add a new one. The pick list value accepts all alphanumeric and special characters.
Example:"Industry": "automobile" - Multi-select picklistJSON array
You can either pass existing pick list values or add a new one. The pick list value accepts all alphanumeric and special characters..
Example:"Courses_Opted": [
"Analytics",
"Big data"
] - Datestring
Accepts date in yyyy-MM-dd format.
Example:"Date_Time": "2017-08-16T14:32:23+05:30". Date_Time is in ISO8601 format and the time zone is the current user's time zone. - Date/Timestring
Accepts date and time in yyyy-MM-ddTHH:mm:ss±HH:mm ISO 8601 format.
Example:"Date_1": "2017-08-16" - Numberinteger
Accepts numbers up to 9 digits. This limit may vary based on the value configured in 'Maximum digits allowed' in the properties pop-up of the field, in UI. Accepts only numeric values.
- Currencydouble
Before decimal point - accepts numbers up to 16 digits. This limit may vary based on the value configured in 'Maximum digits allowed' in the properties pop-up of the field, in UI.
After decimal point - accepts precision up to 9 digits. This limit may vary based on the value configured in 'Number of decimal paces' in the properties pop-up of the field, in UI. Accepts only numeric values.
Example:"Annual_Revenue": 250000.90 - Decimaldouble
Before decimal point - accepts numbers up to 16 digits. This limit may vary based on the value configured in 'Maximum digits allowed' in the properties pop-up of the field, in UI.
After decimal point - accepts precision up to 9 digits. This limit may vary based on the value configured in 'Number of decimal places' in the properties pop-up of the field, in UI.
Accepts only numeric values..
Example:"Decimal_1": 250000.50 - Percentdouble
Accepts numbers up to 5 digits and only numeric values.
Example:"Percentage": 25 - Long Integerstring
Accepts numbers up to 18 digits. This limit may vary based on the value configured in 'Maximum digits allowed' in the properties pop-up of the field, in UI. Accepts only numeric values.
Example:"EAN_Code":"0012345600012" - Checkboxboolean
Accepts only Boolean values (true,false)
Example:"Email_Opt_Out": true - URLstring
Accepts valid URLs. The regex pattern in Bigin to validate this field's value is "^(http:\\/\\/www.|https:\\/\\/www.|ftp:\\/\\/www.|www.|http:\\/\\/|https:\\/\\/|ftp:\\/\\/|){1}[^\\x00-\\x19\\x22-\\x27\\x2A-\\x2C\\x2E-\\x2F\\x3A-\\x40\\x5B-\\x5E\\x60\\x7B\\x7D-\\x7F]+(\\.[^\\x00-\\x19\\x22\\x24-\\x2C\\x2E-\\x2F\\x3C\\x3E\\x40\\x5B-\\x5E\\x60\\x7B\\x7D-\\x7F]+)+(\\/[^\\x00-\\x19\\x22\\x3C\\x3E\\x5E\\x7B\\x7D-\\x7D\\x7F]*)*$"
Example:"URL": "https://www.zylker.com"
Sample Input
Copied{
"data": [
{
"Last_Name": "Daly",
"First_Name": "Paul",
"Email": "p.daly@zylker.com"
},
{
"Last_Name": "Dolan",
"First_Name": "Brian",
"Email": "brian@villa.com"
}
],
"trigger": [
"approval",
"workflow"
]
}
Possible Errors
- INVALID_MODULEHTTP 400
The module name given seems to be invalid
Resolution: You have specified an invalid module name or there is no tab permission, or the module could have been removed from the available modules. Specify a valid module API name. - INVALID_MODULEHTTP 400
The given module is not supported in API
Resolution: The modules such as Documents and Projects are not supported in the current API. (This error will not be shown, once these modules are been supported). Specify a valid module API name. - NO_PERMISSION 403
Permission denied to create '{modulename}'
Resolution:No permission to insert records. - MANDATORY_NOT_FOUNDHTTP 400
Required field not found
Resolution: Required field not found. If the data key isn't available { "api_name": "data" } - INVALID_DATAHTTP 202
Invalid Data
Resolution: If the record passed isn't a JSON object { "expected_data_type":"jsonobject", "index": 0 } - MANDATORY_NOT_FOUNDHTTP 202
Required field not found
Resolution: If the mandatory fields are not available { "api_name":"Last_Name" } - INVALID_DATAHTTP 202
Invalid Data
Resolution: If the data type is mismatched { "expected_data_type":"double", "api_name":"Decimal_1" } - INVALID_DATAHTTP 400
Invalid Data
Resolution: If the data key has the invalid data type { "expected_data_type":"jsonarray", "api_name": "data" },
Sample Response
Copied{
"data": [
{
"code": "SUCCESS",
"details": {
"Modified_Time": "2019-05-02T11:17:33+05:30",
"Modified_By": {
"name": "Patricia Boyle",
"id": "554023000000235011"
},
"Created_Time": "2019-05-02T11:17:33+05:30",
"id": "554023000000527002",
"Created_By": {
"name": "Patricia Boyle",
"id": "554023000000235011"
}
},
"message": "record added",
"status": "success"
},
{
"code": "SUCCESS",
"details": {
"Modified_Time": "2019-05-02T11:17:33+05:30",
"Modified_By": {
"name": "Patricia Boyle",
"id": "554023000000235011"
},
"Created_Time": "2019-05-02T11:17:33+05:30",
"id": "554023000000527003",
"Created_By": {
"name": "Patricia Boyle",
"id": "554023000000235011"
}
},
"message": "record added",
"status": "success"
}
]
}