Create Bulk Write Job

Purpose

To create a bulk write job.

Request URL

https://www.zohoapis.com/crm/bulk/v2/write

Request Method

POST

Scope

scope=ZohoCRM.bulk.CREATE
(or)
ZohoCRM.bulk.ALL
(and)
scope=ZohoCRM.modules.ALL
(or)
Scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names	Possible operation types
leads, accounts, contacts, deals, campaigns, cases, solutions, products, vendors, pricebooks, and custom	ALL - Full access to the record CREATE - Create a bulk write job

Request JSON

Attribute

Data Type

Mandatory

Description

character_encoding

String

Represents the charset of the uploaded file. It is usually auto-detected. But if specified, then it will be used to read the file.

operation

String

Yes

Represents the type of operation you want to perform on the bulk write job.
Values are

insert - To create CSV records as new records in CRM
update - To update an existing record in CRM(This operation does not allow creation of new records).
upsert - To update an existing record in CRM and create new records, if it does not exist already

callback Show properties

JSON Object

A valid URL which should allow HTTP POST method. The Bulk Write Job's details are posted to this URL on successful completion of job or on failure of job. Sample - "callback" : { "url": "https://sampledomain.com/getzohoresponse", "method": "post" }

callback Properties

Attributes	Data Type	Mandatory	Description
url	String(URL)	Yes	A valid URL, which should allow HTTP POST method. The Bulk Write Job's details are posted to this URL on successful completion of job or on failure of job.
method	String	Yes	Specifies the HTTP method of the callback url. Only HTTP POST method is supported. The allowed value is post.

resourceShow properties

JSON Array

A JSON array of objects containing the API names of modules that you want to import, their field mappings, and the corresponding file IDs obtained from Upload API.

resource Properties

Attributes

Data Type

Mandatory

Description

type

String

Yes

Represents the type of module that you want to import. The value is data.

module

String

Yes

API name of the module that you select for bulk write job.

file_id

String

Yes

Represents the file_id obtained from file upload API.

ignore_empty

Boolean

True - Ignores the empty values in a column and updates only the fields of a record without empty values
False or empty - The system updates records in CRM with empty values in the given file column.
The default value is false.

find_by

String

Yes(for update and upsert)
No(for insert)

Specify the API name of a unique field or ID of a record. System uses the value of this field to find the existing records in CRM. When you specify this parameter for insert operation, the system will skip the existing records from the file.

field_mappings
Show properties

JSON Array

When the system processes a CSV file, the first row is treated as header row. Each header name is treated as field API name and data from a column is populated into the corresponding field represented by the API name. This parameter helps you to skip the auto-mapping and define your own field mapping.

field_mappings Properties

Attributes	Data Type	Mandatory	Description
api_name	String	Yes	API name of the field present in Zoho module object that you want to import. Refer Fields Meta Data API for the list of fields available in a module. An invalid field API name throws an error.
index	Number	No	The column index of the field you want to map to the CRM field. When you specify a non-existing index value, the system throws an error.
default_value	JSON Object	No	Use this key if some of the records do not have a value in a column, and you want to replace it with a default value. Example: {"value": "Trade Show"}

Response Structure

Attribute

Data Type

Description

status

String

Specifies the status of the API call. Sample - "status": "success".

message

String

Specifies the pre-defined comments for the job. Useful in case any errors occur.

details Show properties

JSON Object

Please refer the below table for information on the "details" JSON object.

details Properties

Attributes	Data Type	Description
id	String	Specifies the unique identifier of the bulk write job. Sample - "id": "1000010760002".
created_by	JSON Object	Specifies the ID and Name of the user who initiated the bulk write job. Sample - "created_by": { "id": "1000000031045", "name": "Patricia Boyle" },

Possible Errors

HTTP Status	Error Code	Message	Reason
400	MANDATORY_FIELDS_NOT_MAPPED	All mandatory fields are not mapped	All mandatory fields in the module are not mapped
400	MANDATORY_NOT_FOUND	Mandatory key is not available	Mandatory key or value is not specified in the request body. Example: "message": "Required key find_by is not available".
400	INVALID_FIELD	invalid mapping. invalid api_name {{api_name}}	The field API name is invalid
400	INVALID_FORMAT	invalid mapping. invalid format Invalid format for sysref - {field_api_name}	Date is entered in the wrong format
400	INVALID_FILE_ID	invalid file_id {{file_id}}	The file ID specified is invalid
400	HEADER_LIMIT_EXCEEDED	Import file does not exceed 200 columns	The number of fields mapped has exceeded the maximum limit of 200
400	COLUMN_INDEX_NOT_FOUND	Invalid column index mapped. Index is invalid for sysref {field_api_name}.	Index is mapped with negative values
400	MODULE_NOT_AVAILABLE	Requested module {module_api_name} is not available	The module name specified is invalid

Curl Csharp

Sample Request

In the request, @inputData.json contains the sample input data.


				curl "https://www.zohoapis.com/crm/bulk/v2/write"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@inputData.json"

Sample Input for Bulk Insert


				{
  "operation": "insert",
  "callback": {
    "url": "http://requestbin.fullcontact.com/1fcimk51",
    "method": "post"
  },
  "resource": [
    {
      "type": "data",
      "module": "Contacts",
      "file_id": "111111000000541958",
      "field_mappings": [
        {
          "api_name": "Phone",
          "index": 0
        },
        {
          "api_name": "Email",
          "index": 1
        },
        {
          "api_name": "Last_Name",
          "default_value": {
            "value": "DefaultValue"
          }
        }
      ]
    }
  ]
}

Sample Input for Bulk Update


				{
  "operation": "update",
  "resource": [
    {
      "type": "data",
      "module": "Contacts",
      "file_id": "111111000000541958",
      "field_mappings": [
        {
          "api_name": "Last_Name",
          "index": 0
        },
        {
          "api_name": "Id",
          "index": 1
        }
      ],
      "find_by": "Id"
    }
  ],
  "callBack": {
    "url": "http://requestbin.fullcontact.com/1bvgfh61",
    "method": "post"
  }
}

Sample Response


				{
  "status": "success",
  "code": "SUCCESS",
  "message": "success",
  "details": {
    "id": "111111000000541958",
    "created_by": {
      "id": "111111000000035795",
      "name": "Patricia Boyle "
    }
  }
}

Sample Input for Bulk Write


				ZCRMBulkWrite writeJob = ZCRMRestClient.GetInstance().GetBulkWriteInstance(); // To get ZCRMBulkWrite instance
writeJob.Operation = "insert"; //To set the type of operation you want to perform on the bulk write job.
writeJob.CharacterEncoding = "UTF-8";
ZCRMBulkCallBack callBack = ZCRMBulkCallBack.GetInstance();
callBack.Url = "https://www.zoho.com/";
callBack.Method = "post";
writeJob.Callback = callBack;
ZCRMBulkWriteResource resourceIns = ZCRMBulkWriteResource.GetInstance("ModuleAPIName", 432421441); //Specify the ModuleAPIName and the uploaded file Id.
resourceIns.Type = "data";// To set the type of module that you want to import. The value is data.
resourceIns.IgnoreEmpty = true;//True - Ignores the empty values.The default value is false. 
ZCRMBulkWriteFieldMapping fieldMappings;
fieldMappings = ZCRMBulkWriteFieldMapping.GetInstance("Last_Name", 0);//To get ZCRMBulkWriteFieldMapping instance using Field APIName and column index of the field in the uploaded file.
resourceIns.SetFieldMapping(fieldMappings);// To set the ZCRMBulkWriteFieldMapping instance to ZCRMBulkWriteResource.
fieldMappings = ZCRMBulkWriteFieldMapping.GetInstance("Email", 1);
resourceIns.SetFieldMapping(fieldMappings);
fieldMappings = ZCRMBulkWriteFieldMapping.GetInstance("Company", 2);
resourceIns.SetFieldMapping(fieldMappings);
fieldMappings = ZCRMBulkWriteFieldMapping.GetInstance("Phone", 3);
resourceIns.SetFieldMapping(fieldMappings);
fieldMappings = ZCRMBulkWriteFieldMapping.GetInstance("Website", null);
fieldMappings.SetDefaultValue("value", "https://www.zohoapis.com");//To set the default value for an empty column in the uploaded file.
resourceIns.SetFieldMapping(fieldMappings);
writeJob.SetResource(resourceIns);// To set ZCRMBulkWriteFieldMapping instance
APIResponse resp = writeJob.CreateBulkWriteJob();// To create bulk write job.

Sample Input Bulk Update


				ZCRMBulkWrite writeJob = ZCRMRestClient.GetInstance().GetBulkWriteInstance();
writeJob.CharacterEncoding = "UTF-8";
writeJob.Operation = "update";
ZCRMBulkCallBack callBackIns = ZCRMBulkCallBack.GetInstance("https://www.zoho.com", "post");
writeJob.Callback = callBackIns;
ZCRMBulkWriteResource resourceIns = ZCRMBulkWriteResource.GetInstance("ModuleAPIName", "432421441"); //432421441 uploaded file id
resourceIns.IgnoreEmpty = true;
resourceIns.FindBy = "Email";// To set a field as a unique field or ID of a record. 
resourceIns.Type = "data";
ZCRMBulkWriteFieldMapping fieldMappings;
fieldMappings = ZCRMBulkWriteFieldMapping.GetInstance("Last_Name", 0);
resourceIns.SetFieldMapping(fieldMappings);

fieldMappings = ZCRMBulkWriteFieldMapping.GetInstance("Email", 1);
resourceIns.SetFieldMapping(fieldMappings);

fieldMappings = ZCRMBulkWriteFieldMapping.GetInstance("Company", 2);
resourceIns.SetFieldMapping(fieldMappings);

fieldMappings = ZCRMBulkWriteFieldMapping.GetInstance("Phone", 3);
resourceIns.SetFieldMapping(fieldMappings);

fieldMappings = ZCRMBulkWriteFieldMapping.GetInstance("Website", null);
fieldMappings.SetDefaultValue("value", "https://www.zohoapis.com");
resourceIns.SetFieldMapping(fieldMappings);

fieldMappings = ZCRMBulkWriteFieldMapping.GetInstance("Contacts", 4);
fieldMappings.FindBy = "Email";// To set a field as a unique field or ID of a record. 
resourceIns.SetFieldMapping(fieldMappings);
writeJob.SetResource(resourceIns);
APIResponse resp = writeJob.CreateBulkWriteJob();

Sample Response


				{
  "status": "success",
  "code": "SUCCESS",
  "message": "success",
  "details": {
    "id": "111111000000541958",
    "created_by": {
      "id": "111111000000035795",
      "name": "Patricia Boyle "
    }
  }
}