Create Bulk Write Job

Purpose

To create a bulk write job to import records into CRM.

Request Details

Request URL

{api-domain}/crm/bulk/{version}/write

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

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

Possible module names

leads, accounts, contacts, deals, campaigns, cases, solutions, products, vendors, pricebooks, tasks, and custom

Possible operation types

ALL - Full access to the record
CREATE - Create a bulk write job

Sample request

Copiedcurl "https://www.zohoapis.com/crm/bulk/v2.1/write"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@inputData.json"
4.0.04.x
Copied//Get instance of BulkWriteOperations Class
$bulkWriteOperations = new BulkWriteOperations();
//Get instance of RequestWrapper Class that will contain the request body
$requestWrapper = new RequestWrapper();
//Get instance of CallBack Class
$callback = new CallBack();
// To set valid callback URL.
$callback->setUrl("https://www.example.com/callback");
//To set the HTTP method of the callback URL. The allowed value is post.
$callback->setMethod(new Choice("post"));
//The Bulk Write Job's details are posted to this URL on successful completion of job or on failure of job.
$requestWrapper->setCallback($callback);
//To set the charset of the uploaded file
$requestWrapper->setCharacterEncoding("UTF-8");
//To set the type of operation you want to perform on the bulk write job.
$requestWrapper->setOperation(new Choice("insert"));
$resource = array();
//Get instance of Resource Class
$resourceIns = new Resource();
// To set the type of module that you want to import. The value is data.
$resourceIns->setType(new Choice("data"));
$module = new Module();
$module->setAPIName($moduleAPIName);
//To set API name of the module that you select for bulk write job.
$resourceIns->setModule($module);
//To set the file_id obtained from file upload API.
$resourceIns->setFileId($fileId);
//True - Ignores the empty values.The default value is false.
$resourceIns->setIgnoreEmpty(true);
// To set a field as a unique field or ID of a record.
$resourceIns->setFindBy("Email");
$fieldMappings = array();
//Get instance of FieldMapping Class
$fieldMapping = new FieldMapping();
//To set API name of the field present in Zoho module object that you want to import.
$fieldMapping->setAPIName("Last_Name");
//To set the column index of the field you want to map to the CRM field.
$fieldMapping->setIndex(0);
array_push($fieldMappings, $fieldMapping);
$fieldMapping = new FieldMapping();
$fieldMapping->setAPIName("Email");
$fieldMapping->setIndex(1);
array_push($fieldMappings, $fieldMapping);
$fieldMapping = new FieldMapping();
$fieldMapping->setAPIName("Company");
$fieldMapping->setIndex(2);
array_push($fieldMappings, $fieldMapping);
$fieldMapping = new FieldMapping();
$fieldMapping->setAPIName("Phone");
$fieldMapping->setIndex(3);
array_push($fieldMappings, $fieldMapping);
$fieldMapping = new FieldMapping();
$fieldMapping->setAPIName("Website");
//$fieldMapping->setFormat("");
//$fieldMapping->setFindBy("");
$defaultValue = array();
$defaultValue["value"] = "https://www.zohoapis.com";
//To set the default value for an empty column in the uploaded file.
$fieldMapping->setDefaultValue($defaultValue);
array_push($fieldMappings, $fieldMapping);
$resourceIns->setFieldMappings($fieldMappings);
array_push($resource, $resourceIns);
$requestWrapper->setResource($resource);
//Call createBulkWriteJob method that takes RequestWrapper instance as parameter
$response = $bulkWriteOperations->createBulkWriteJob($requestWrapper);
Copied<?php

class CreateBulkWriteJob
{
	public function execute(){
        $curl_pointer = curl_init();
        
        $curl_options = array();
        $curl_options[CURLOPT_URL] = "https://www.zohoapis.com/crm/bulk/v2.1/write";
        $curl_options[CURLOPT_RETURNTRANSFER] = true; 
        $curl_options[CURLOPT_HEADER] = 1;
        $curl_options[CURLOPT_CUSTOMREQUEST] = "POST";
        $requestBody=array();
        $requestBody["ignore_empty"]=true;
        $resource=array();
        $resourceObject=array();
        $field_mappings=array();
        $field_mappingsObject=array();
        $field_mappingsObject["api_name"]="Last_Name";
        $field_mappingsObject["index"]=0;
        array_push($field_mappings,$field_mappingsObject);
        $field_mappingsObject1=array();
        $field_mappingsObject1["api_name"]="Id";
        $field_mappingsObject1["index"]=1;
        array_push($field_mappings,$field_mappingsObject1);
        $resourceObject["field_mappings"]=$field_mappings;
        $module=array();
        $module["api_name"]="Contacts";
        $module["id"]="3652397000000002179";
        $resourceObject["module"]=$module;
        $resourceObject["file_id"]="111111000000541958";
        $resourceObject["find_by"]="Id";
        $resourceObject["type"]="data";
        array_push($resource,$resourceObject);
        $requestBody["resource"]=$resource;
        $callBack=array();
        $callBack["method"]="post";
        $callBack["url"]="http://requestbin.fullcontact.com/1bvgfh61";
        $requestBody["callBack"]=$callBack;
        $requestBody["operation"]="update";
        
        
        $curl_options[CURLOPT_POSTFIELDS]= json_encode($requestBody);
        $headersArray = array();

        $headersArray[] = "Authorization". ":" . "Zoho-oauthtoken " ."1000.bb75eXXXXX996e043dcfbb.5e2444e9XXXXXc8d9f536e";
        $headersArray[] = "Content-Type".":"."application/json";
        $curl_options[CURLOPT_HTTPHEADER]=$headersArray;
        
        curl_setopt_array($curl_pointer, $curl_options);

        $result = curl_exec($curl_pointer);
        $responseInfo = curl_getinfo($curl_pointer);
        curl_close($curl_pointer);
        list ($headers, $content) = explode("\r\n\r\n", $result, 2);
        if(strpos($headers," 100 Continue")!==false){
            list( $headers, $content) = explode( "\r\n\r\n", $content , 2);
        }
        $headerArray = (explode("\r\n", $headers, 50));
        $headerMap = array();
        foreach ($headerArray as $key) {
            if (strpos($key, ":") != false) {
                $firstHalf = substr($key, 0, strpos($key, ":"));
                $secondHalf = substr($key, strpos($key, ":") + 1);
                $headerMap[$firstHalf] = trim($secondHalf);
            }
        }
        $jsonResponse = json_decode($content, true);
        if ($jsonResponse == null && $responseInfo['http_code'] != 204) {
            list ($headers, $content) = explode("\r\n\r\n", $content, 2);
            $jsonResponse = json_decode($content, true);
        }
        var_dump($headerMap);
        var_dump($jsonResponse);
        var_dump($responseInfo['http_code']);
       
    }
    
}
(new CreateBulkWriteJob())->execute();
2.1.0
Copied# """
cvid = '3524033000000087501'
# Get instance of BulkWriteOperations Class
bwo = BulkWrite::BulkWriteOperations.new
# Get instance of RequestWrapper Class that will contain the request body
request_wrapper = BulkWrite::RequestWrapper.new
# Get instance of CallBack Class
call_back = BulkWrite::CallBack.new
# Set valid callback URL
call_back.url = 'https://www.example.com/callback'
# Set the HTTP method of the callback URL. The allowed value is post.
call_back.method = Util::Choice.new('post')
# The Bulk Read Job's details is posted to this URL on successful completion / failure of the job.
request_wrapper.callback = call_back
# Set the charset of the uploaded file
request_wrapper.character_encoding = 'UTF-8'
# To set the type of operation you want to perform on the bulk write job.
request_wrapper.operation = Util::Choice.new('insert')
# Get instance of Resource Class
resource_ins = BulkWrite::Resource.new
# To set the type of module that you want to import. The value is data.
resource_ins.type = Util::Choice.new('data')
# To set API name of the module that you select for bulk write job.
resource_ins.module = module_api_name
# To set the fileId obtained from file upload API.
resource_ins.file_id = file_id
# True - Ignores the empty values.The default value is false.
resource_ins.ignore_empty = true
# Get instance of FieldMapping Class
field_mapping0 = BulkWrite::FieldMapping.new
# To set API name of the field present in Zoho module object that you want to import.
field_mapping0.api_name = 'Last_Name'
# To set the column index of the field you want to map to the CRM field.
field_mapping0.index = 0
field_mapping1 = BulkWrite::FieldMapping.new
field_mapping1.api_name = 'Email'
field_mapping1.index = 1
field_mapping2 = BulkWrite::FieldMapping.new
field_mapping2.api_name = 'Company'
field_mapping2.index = 2
field_mapping3 = BulkWrite::FieldMapping.new
field_mapping3.api_name = 'Phone'
field_mapping3.index = 3
field_mapping4 = BulkWrite::FieldMapping.new
field_mapping4.api_name = 'Website'
# To set the default value for an empty column in the uploaded file.
default_value = { 'value' => 'https://www.zohoapis.com' }
# To set the default value for an empty column in the uploaded file.
field_mapping4.default_value = default_value
field_mappings = [field_mapping0, field_mapping1, field_mapping2, field_mapping3, field_mapping4]
resource_ins.field_mappings = field_mappings
resource = [resource_ins]
# Set the list of resources to RequestWrapper instance
request_wrapper.resource = resource
# Call create_bulk_write_job method that takes RequestWrapper instance as parameter
response = bwo.create_bulk_write_job(request_wrapper)
Copiedrequire 'net/http'
require 'json'

class CreateBulkWriteJob
    def execute
       
        url ="https://www.zohoapis.com/crm/bulk/v2.1/write";
        url = URI(url)
        req = Net::HTTP::Post.new(url.request_uri)
        http = Net::HTTP.new(url.host, url.port)
        http.use_ssl = true
        headers={}
        headers["Authorization"]="Zoho-oauthtoken 1000.dfa7XXXXXXXXXXXXXXXXXX84f9665840.c176aeXXXXXXXXXXXX13f3d37a84d"
        headers["Content-Type"]="application/json";
        headers&.each { |key, value| req.add_field(key, value) }
       
        request_body = {};
        callback = {}
        callback["url"]="https://www.example.com/callback";
        callback["method"]="post";
        query = {}
        query["module"]="Contacts";
        fields = ["Last_Name","Owner","Owner.last_name","Account_Name.Account_Name"]
        request_body["callback"] =callback;
        query["fields"]=fields;
        criteria = {}
        criteria["group_operator"]="or";
        group = {}
        criteria1 = {}
        criteria1["api_name"]="Lead_Source";
        criteria1["comparator"]="equal";
        criteria1["value"]="Advertisement";
        criteria2 = {} 
        criteria2["api_name"]="Owner.last_name";
        criteria2["comparator"]="equal";
        criteria2["value"]="Boyle";
        criteria3 = {}
        criteria3["api_name"]="Account_Name.Phone";
        criteria3["comparator"]="contains";
        criteria3["value"]="5";
        group = [criteria1,criteria2,criteria3];
        criteria["group"] = group;
        query["criteria"] =criteria;
        query["page"] =1;
        request_body["query"]=query;
        request_json = request_body.to_json
        req.body = request_json.to_s
        response=http.request(req)
        status_code = response.code.to_i
        headers = response.each_header.to_h
        print status_code
        print headers
        unless response.body.nil?
            print  response.body
        end
    end
end

CreateBulkWriteJob.new.execute

Request JSON

  • character_encodingString, optional

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

  • operationString, mandatory

    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 they do not exist already.
  • ignore_emptyBoolean, optional

    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.

  • callbackJSON Object, optional

    A valid URL that allows the HTTP POST method. The Bulk Write Job's details are posted to this URL on successful completion or failure of a job. Sample - "callback" : { "url": "https://sampledomain.com/getzohoresponse", "method": "post" }.
    This JSON Object takes two keys—url and method.

    • url(string) - A valid URL, which should allow HTTP POST method. The Bulk Write Job's details are posted to this URL on successful completion or failure of a job.

    • method(string) - The HTTP method of the callback url. The supported value is post.

  • resourceJSON array, optional

    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.

    • type(string, mandatory) - Represents the type of module that you want to import. The value is data.

    • module(string, mandatory) - The API name of the module that you select for bulk write job.
      For subforms: When you want to bulk-write subform data, you must give the API name of the subform here.

    • file_id(string, mandatory) - The file_id obtained from file upload API.

    • find_by(string, mandatory for update and upsert, optional for insert) - The API name of a unique field or ID of a record. The 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(JSON array, optional) - When the system processes a CSV file, the first row is treated as the header row. Each header name is treated as the field API name and data from a column are populated into the corresponding field represented by the API name. This parameter helps you to skip auto-mapping and define your own field mapping. Note that if you include this array in the input, data in the CSV will be mapped based only on the index value in this array.

      • api_name(string, mandatory) - The 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, optional) - 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.

      • find_by(string, mandatory for lookup fields) - The API name of the unique field in the module against which the system checks if there are existing records in CRM. You can also use id, API names of the system-defined unique fields, custom unique fields, lookup fields, and display columns/fields(the results displayed based on a field, that are listed when you search for an associated lookup. For example, Account Name is the display column when you have a look up in Contacts that points to Accounts.) as find_by fields.

      • default_value(JSON object, optional) - 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"}.

    For Subforms
    • The field_mappings array must have the following mandatory object, besides the details of the other fields of the subform. This is to map the subform record with the respective parent record.

      "api_name":"Parent_Id",
      "find_by":"id",
      "index":"the_index_in_the_csv"
Note
  • You can bulk-insert records in a specific layout of a module. Note that when you insert records using bulk-write the system ignores the custom layout-specific mandatory fields.

  • To insert the records in a specific layout, you must specify the name of the custom layout in your CSV file. If left unspecified/incorrect value specified, the system inserts the records in the default layout in that module. Also, you must specify the relevant details in the field_mappings key in the input. Refer to sample input for more details.

  • For field-types such as Date and Date/Time, there are default formats. For instance, for Date, the default format is MM/dd/yyyy, and for Date/Time, the default format is MM/dd/yyyy HH:mm:ss. If you specify the value for these fields in any other format in your CSV file, you must specify the format in your input. Refer to sample input for more details. Click here to know the allowed formats for Date, Date/Time, and Number fields.

Sample input to bulk-insert Subform data

Copied{
 "operation": "insert",
 "ignore_empty": true,
 "callback": {
  "url": "http://requestbin.fullcontact.com/1fcimk51",
  "method": "post"
 },
 "resource": [
  {
   "type": "data",
   "module": "Contact_Sub",//The API name of the subform in the Contacts module
   "file_id": "111111000000541958",
   "field_mappings": [
    {
     "api_name": "Parent_Id",//The CSV must contain the parent record ID of the contact 
     "find_by": "id",
     "index": 3
    },
    {
     "api_name": "Secondary Phone",
     "index": 1
    },
    {
     "api_name": "Secondary Email",
     "index": 0
    }
   ]
  }
 ]
}

Sample input for bulk update

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

Response Structure

  • statusstring

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

  • messagestring

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

  • detailsJSON object

    Contains the following details of the bulk write job.

    • 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

  • MANDATORY_FIELDS_NOT_MAPPED HTTP 400

    All the mandatory fields in the module are not mapped.
    Resolution: Map all the mandatory fields in the module.

  • MANDATORY_NOT_FOUND HTTP 400

    Mandatory key or value is not specified in the request body. Example: "message": "Required key find_by is not available".
    Resolution: Include the required key in the input.

  • INVALID_FIELD HTTP 400

    The field API name is invalid.
    Resolution: Specify the correct API name of the field.

  • INVALID_FORMAT HTTP 400

    You have entered the date in the wrong format.
    Resolution: Input the date in the correct format.

  • INVALID_FILE_ID HTTP 400

    The file ID specified is invalid.
    Resolution: Specify the correct file ID you received while uploading the CSV file.

  • HEADER_LIMIT_EXCEEDED HTTP 400

    The number of fields mapped has exceeded the maximum limit of 200.
    Resolution: You can only map up to 200 fields.

  • COLUMN_INDEX_NOT_FOUND HTTP 400

    Index is mapped with negative values.
    Resolution: "index" can only take positive integer values.

  • MODULE_NOT_AVAILABLE HTTP 400

    The module name specified is invalid.
    Resolution: The API name of the module is either wrong or this module is not supported for a bulk write job. Refer to the "Possible module name" section for the list of supported modules.

  • INVALID_URL_PATTERNHTTP 404

    Please check if the URL trying to access is a correct one
    Resolution: The request URL specified is incorrect. Specify a valid request URL. Refer to request URL section above.

  • OAUTH_SCOPE_MISMATCHHTTP 401

    Unauthorized
    Resolution: Client does not have ZohoCRM.bulk.CREATE. Create a new client with valid scope. Refer to scope section above.

  • NO_PERMISSIONHTTP 403

    Permission denied to create
    Resolution: The user does not have permission to create a bulk write job. Contact your system administrator.

  • INTERNAL_ERRORHTTP 500

    Internal Server Error
    Resolution: Unexpected and unhandled exception in Server. Contact support team.

  • INVALID_REQUEST_METHODHTTP 400

    The http request method type is not a valid one
    Resolution: You have specified an invalid HTTP method to access the API URL. Specify a valid request method. Refer to endpoints section above.

  • AUTHORIZATION_FAILEDHTTP 400

    User does not have sufficient privilege to create.
    Resolution: The user does not have the permission to create a bulk write job. Contact your system administrator.

Sample response

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