Create Bulk Write Job

Purpose

To create a bulk write job.

Request Details

Request URL

https://www.zohoapis.com/bigin/bulk/v1/write

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

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

Possible module names

companies, contacts, deals, tasks, events, calls, products and activities.

Possible operation types

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

Sample request

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

CopiedZBiginBulkWrite writeJob = ZBiginRestClient.GetInstance().GetBulkWriteInstance(); // To get ZBiginBulkWrite instance
writeJob.Operation = "insert"; //To set the type of operation you want to perform on the bulk write job.
writeJob.CharacterEncoding = "UTF-8";
ZBiginBulkCallBack callBack = ZBiginBulkCallBack.GetInstance();
callBack.Url = "https://www.zoho.com/";
callBack.Method = "post";
writeJob.Callback = callBack;
ZBiginBulkWriteResource resourceIns = ZBiginBulkWriteResource.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. 
ZBiginBulkWriteFieldMapping fieldMappings;
fieldMappings = ZBiginBulkWriteFieldMapping.GetInstance("Last_Name", 0);//To get ZBiginBulkWriteFieldMapping instance using Field APIName and column index of the field in the uploaded file.
resourceIns.SetFieldMapping(fieldMappings);// To set the ZBiginBulkWriteFieldMapping instance to ZBiginBulkWriteResource.
fieldMappings = ZBiginBulkWriteFieldMapping.GetInstance("Email", 1);
resourceIns.SetFieldMapping(fieldMappings);
fieldMappings = ZBiginBulkWriteFieldMapping.GetInstance("Company", 2);
resourceIns.SetFieldMapping(fieldMappings);
fieldMappings = ZBiginBulkWriteFieldMapping.GetInstance("Phone", 3);
resourceIns.SetFieldMapping(fieldMappings);
fieldMappings = ZBiginBulkWriteFieldMapping.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 ZBiginBulkWriteFieldMapping instance
APIResponse resp = writeJob.CreateBulkWriteJob();// To create bulk write job.

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 Bigin.
- update - To update an existing record in Bigin(This operation does not allow creation of new records).
- upsert - To update an existing record in Bigin and create new records, if they do not exist already.
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.
- file_id(string, mandatory) - The file_id obtained from file upload API.
- ignore_empty(boolean, 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 Bigin with empty values in the given file column.
  The default value is false.
- 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 Bigin. 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.
  - 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 Bigin field. When you specify a non-existing index value, the system throws an error.
  - 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"}.

Sample input for bulk insert

Copied{
  "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

Copied{
  "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"
  }
}

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 ZohoBigin.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 "
    }
  }
}

Sample input for bulk update

Copied{
  "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"
  }
}