openapi: 3.1.0 info: title: Helpcenter Write API version: 1.0.0 tags: - name: Write 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 tags: - Write /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 maxLength: 100 required: - api_name - index file: type: object description: File processing details additionalProperties: false properties: status: type: string description: File processing status enum: - COMPLETED - ADDED - INPROGRESS - SKIPPED name: type: string description: File name maxLength: 255 added_count: type: integer format: int32 description: Number of records added skipped_count: type: integer format: int32 description: Number of records skipped updated_count: type: integer format: int32 description: Number of records updated total_count: type: integer format: int32 description: Total number of records required: - status - name - added_count - skipped_count - updated_count - total_count code: type: string description: Response code maxLength: 100 required: - status - type - module id: type: string description: Bulk write job ID maxLength: 100 result: type: object description: Job result details additionalProperties: false properties: download_url: type: string description: URL to download the result maxLength: 500 required: - download_url created_by: type: object description: User who created the job additionalProperties: false properties: name: type: string description: User name maxLength: 100 id: type: string description: User ID maxLength: 100 required: - name - id operation: type: string description: Type of operation performed maxLength: 50 created_time: type: string format: date-time description: Job creation timestamp callback: type: object description: Callback configuration additionalProperties: false properties: url: type: string description: Callback URL enum: - http://requestbin.fullcontact.com/1fcimk51 method: type: string description: Callback HTTP method enum: - post required: - url - method required: - status - resource - id - created_by - operation - created_time - callback security: - iam-oauth2-schema: - ZohoCRM.bulk.CREATE tags: - Write components: parameters: JobId: name: jobId in: path required: true description: Unique identifier of the bulk write job schema: type: string maxLength: 100 securitySchemes: iam-oauth2-schema: $ref: ./Common.json#/components/securitySchemes/iam-oauth2-schema x-entity: Helpcenter