Bulk Write API allows you to insert, update, or upsert a large set of data. Published by Zoho in its first-party OpenAPI 3.1.0 repository github.com/zoho/crm-oas; 2 operation(s).
{
"openapi": "3.1.0",
"info": {
"title": "Bulk Write",
"description": "Bulk Write API allows you to insert, update, or upsert a large set of data.",
"version": "8"
},
"servers": [
{
"url": "https://zohoapis.{dc}/crm/bulk/{version}",
"description": "API Server URL",
"variables": {
"dc": {
"description": "API Server URL TLD",
"default": "com",
"enum": [
"eu",
"com",
"au",
"in",
"jp",
"cn",
"ca"
]
},
"version": {
"description": "API Version",
"default": "v8"
}
}
}
],
"paths": {
"/write": {
"post": {
"summary": "Create Bulk Write Job",
"description": "Creates a new bulk write job to insert or update records in bulk",
"operationId": "createBulkWriteJob",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Bulk write job creation request",
"additionalProperties": false,
"properties": {
"character_encoding": {
"type": [
"string",
"null"
],
"description": "Character encoding of the file",
"maxLength": 50
},
"operation": {
"type": "string",
"description": "Type of bulk operation to perform",
"enum": [
"insert",
"update",
"upsert"
]
},
"callback": {
"type": "object",
"description": "Callback configuration for job completion notification",
"additionalProperties": false,
"properties": {
"url": {
"type": "string",
"description": "Callback URL to receive job completion notification",
"format": "uri"
},
"method": {
"type": "string",
"description": "HTTP method for callback",
"enum": [
"post"
]
}
},
"required": [
"url",
"method"
]
},
"resource": {
"type": "array",
"description": "List of resources to process in bulk",
"maxItems": 100,
"items": {
"type": "object",
"description": "Resource configuration for bulk operation",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"description": "Type of resource",
"enum": [
"data"
]
},
"file_names": {
"type": "array",
"description": "List of file names to process",
"maxItems": 10,
"items": {
"type": "string",
"description": "File name",
"maxLength": 255
}
},
"module": {
"type": "object",
"description": "Target module for bulk operation",
"additionalProperties": false,
"properties": {
"api_name": {
"type": "string",
"description": "API name of the module",
"maxLength": 100
}
},
"required": [
"api_name"
]
},
"file_id": {
"type": "string",
"description": "ID of the uploaded file",
"maxLength": 100
},
"ignore_empty": {
"type": "boolean",
"description": "Whether to ignore empty values"
},
"find_by": {
"type": "string",
"description": "Field to use for finding existing records",
"enum": [
"id"
]
},
"field_mappings": {
"type": "array",
"description": "Mapping between file columns and module fields",
"maxItems": 500,
"items": {
"type": "object",
"description": "Field mapping configuration",
"additionalProperties": false,
"properties": {
"api_name": {
"type": "string",
"description": "API name of the field",
"maxLength": 100
},
"index": {
"type": "integer",
"format": "int32",
"description": "Column index in the file"
}
},
"required": [
"api_name",
"index"
]
}
}
},
"required": [
"type",
"file_names",
"module",
"file_id",
"find_by"
]
}
}
},
"required": [
"operation",
"resource"
]
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Bulk write job created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Successful bulk write job creation response",
"additionalProperties": false,
"properties": {
"status": {
"type": "string",
"description": "Status of the operation",
"enum": [
"success"
]
},
"code": {
"type": "string",
"description": "Response code indicating the result",
"enum": [
"SUCCESS",
"FILE_UPLOAD_SUCCESS"
]
},
"message": {
"type": "string",
"description": "Response message",
"enum": [
"success",
"file uploaded."
]
},
"details": {
"type": "object",
"description": "Details of the created bulk write job",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the bulk write job",
"maxLength": 100
},
"created_by": {
"type": "object",
"description": "User who created the bulk write job",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"description": "User ID",
"maxLength": 100
},
"name": {
"type": "string",
"description": "User name",
"maxLength": 100
}
},
"required": [
"id"
]
}
},
"required": [
"id",
"created_by"
]
}
},
"required": [
"status",
"code",
"message",
"details"
]
}
}
}
},
"400": {
"description": "Bad Request - Invalid input parameters or validation errors",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "object",
"description": "Invalid callback URL error response",
"additionalProperties": false,
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"INVALID_CALLBACK_URL"
]
},
"details": {
"type": "object",
"description": "Additional error details",
"additionalProperties": true
},
"message": {
"type": "string",
"description": "Error message",
"maxLength": 1000
},
"status": {
"type": "string",
"description": "Response status",
"enum": [
"error"
]
}
}
},
{
"type": "object",
"description": "Invalid data error response",
"additionalProperties": false,
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"INVALID_DATA"
]
},
"details": {
"type": "object",
"description": "Additional error details",
"additionalProperties": true
},
"message": {
"type": "string",
"description": "Error message",
"maxLength": 1000
},
"status": {
"type": "string",
"description": "Response status",
"enum": [
"error"
]
}
}
},
{
"type": "object",
"description": "Mandatory field not found error response",
"additionalProperties": false,
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"MANDATORY_NOT_FOUND"
]
},
"details": {
"type": "object",
"description": "Error details",
"additionalProperties": true
},
"message": {
"type": "string",
"description": "Error message",
"enum": [
"Required key parent_column_index is not available",
"Required key find_by is not available"
]
},
"status": {
"type": "string",
"description": "Response status",
"enum": [
"error"
]
}
}
},
{
"type": "object",
"description": "Coexistence not allowed error response",
"additionalProperties": false,
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"COEXISTENCE_NOT_ALLOWED"
]
},
"status": {
"type": "string",
"description": "Response status",
"enum": [
"error"
]
}
}
},
{
"type": "object",
"description": "File not supported error response",
"additionalProperties": false,
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"FILE_NOT_SUPPORTED"
]
},
"details": {
"type": "object",
"description": "Additional error details",
"additionalProperties": true
},
"message": {
"type": "string",
"description": "Error message",
"maxLength": 1000
},
"status": {
"type": "string",
"description": "Response status",
"enum": [
"error"
]
}
}
},
{
"type": "object",
"description": "File not found error response",
"additionalProperties": false,
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"FILE_NOT_FOUND"
]
},
"details": {
"type": "object",
"description": "Additional error details",
"additionalProperties": true
},
"message": {
"type": "string",
"description": "Error message",
"maxLength": 1000
},
"status": {
"type": "string",
"description": "Response status",
"enum": [
"error"
]
}
}
},
{
"type": "object",
"description": "File not found error response",
"additionalProperties": false,
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"INVALID_REQUEST"
]
},
"details": {
"type": "object",
"description": "Additional error details",
"additionalProperties": true
},
"message": {
"type": "string",
"description": "Error message",
"maxLength": 1000
},
"status": {
"type": "string",
"description": "Response status",
"enum": [
"error"
]
}
}
},
{
"type": "object",
"description": "Mandatory fields not mapped error response",
"additionalProperties": false,
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"MANDATORY_FIELDS_NOT_MAPPED"
]
},
"details": {
"type": "object",
"description": "Additional error details",
"additionalProperties": true
},
"message": {
"type": "string",
"description": "Error message",
"maxLength": 1000
},
"status": {
"type": "string",
"description": "Response status",
"enum": [
"error"
]
}
}
},
{
"type": "object",
"description": "Invalid callback method error response",
"additionalProperties": false,
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"INVALID_CALLBACK_METHOD"
]
},
"details": {
"type": "object",
"description": "Additional error details",
"additionalProperties": false,
"properties": {
"supported_callback_methods": {
"type": "array",
"description": "List of supported callback methods",
"maxItems": 10,
"items": {
"type": "string",
"description": "Callback method",
"maxLength": 50
}
}
}
},
"message": {
"type": "string",
"description": "Error message",
"maxLength": 1000
},
"status": {
"type": "string",
"description": "Response status",
"enum": [
"error"
]
}
}
},
{
"type": "object",
"description": "Missing required key error response",
"additionalProperties": false,
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"MISSING_REQUIRED_KEY"
]
},
"details": {
"type": "object",
"description": "Additional error details",
"additionalProperties": false,
"properties": {
"json_path": {
"type": "string",
"description": "JSON path to the missing key",
"maxLength": 500
}
}
},
"message": {
"type": "string",
"description": "Error message",
"maxLength": 1000
},
"status": {
"type": "string",
"description": "Response status",
"enum": [
"error"
]
}
}
},
{
"type": "object",
"description": "Module not available error response",
"additionalProperties": false,
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"MODULE_NOT_AVAILABLE"
]
},
"details": {
"type": "object",
"description": "Additional error details",
"additionalProperties": true
},
"message": {
"type": "string",
"description": "Error message",
"maxLength": 1000
},
"status": {
"type": "string",
"description": "Response status",
"enum": [
"error"
]
}
}
},
{
"type": "object",
"description": "Request body not supported error response",
"additionalProperties": false,
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"REQUEST_BODY_NOT_SUPPORTED"
]
},
"details": {
"type": "object",
"description": "Additional error details",
"additionalProperties": true
},
"message": {
"type": "string",
"description": "Error message",
"maxLength": 1000
},
"status": {
"type": "string",
"description": "Response status",
"enum": [
"error"
]
}
}
}
]
}
}
}
}
},
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.bulk.CREATE"
]
}
]
}
},
"/write/{jobId}": {
"get": {
"summary": "Get Bulk Write Job Details",
"description": "To upload a CSV file in ZIP format for bulk write API. The response contains the file_id. Use this ID while making the bulk write request.",
"operationId": "getJobDetails",
"parameters": [
{
"$ref": "#/components/parameters/JobId"
}
],
"responses": {
"200": {
"description": "Bulk write job details retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Bulk write job details response",
"additionalProperties": false,
"properties": {
"status": {
"type": "string",
"description": "Status of the bulk write job",
"maxLength": 50
},
"character_encoding": {
"type": "string",
"description": "Character encoding used for the file",
"maxLength": 50
},
"resource": {
"type": "array",
"description": "List of resources processed in the bulk write job",
"maxItems": 100,
"items": {
"type": "object",
"description": "Resource details",
"additionalProperties": false,
"properties": {
"status": {
"type": "string",
"description": "Status of the resource processing",
"enum": [
"COMPLETED",
"ADDED",
"INPROGRESS",
"SKIPPED"
]
},
"type": {
"type": "string",
"description": "Type of resource",
"enum": [
"data"
]
},
"module": {
"type": "object",
"description": "Module information",
"additionalProperties": false,
"properties": {
"api_name": {
"type": "string",
"description": "API name of the module",
"maxLength": 100
},
"id": {
"type": "string",
"description": "Module ID",
"maxLength": 100
}
},
"required": [
"api_name"
]
},
"ignore_empty": {
"type": "boolean",
"description": "Whether empty values are ignored"
},
"field_mappings": {
"type": "array",
"description": "Field mapping configuration",
"maxItems": 500,
"items": {
"type": "object",
"description": "Individual field mapping",
"additionalProperties": false,
"properties": {
"api_name": {
"type": "string",
"description": "API name of the field",
"maxLength": 100
},
"index": {
"type": "integer",
"format": "int32",
"description": "Column index in the file"
},
"format": {
"type": [
"string",
"null"
],
"description": "Format of the field value",
"maxLength": 100
},
"find_by": {
"type": [
"string",
"null"
],
"description": "Field to find records by",
"maxLength": 100
},
"default_value": {
"type": "object",
"description": "Default value configuration",
"additionalProperties": false,
"properties": {
"value": {
"type": "string",
"description": "Default value",
"maxLength": 500
}
},
"required": [
"value"
]
},
"parent_column_index": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Parent column index for related fields"
},
"module": {
"type": [
"string",
"null"
],
"description": "Related module name",
# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zoho-crm/refs/heads/main/openapi/zoho-crm-bulk-write-openapi.json