Bulk Merge

Open in ChatGPT Open in ChatGPT to ask questions about this page
Open in Claude Open in Claude to ask questions about this page
Copy as MarkdownCopy this page as markdown to use with AI assistants
View as Markdown Open this page as markdown in a new tab

Merges data into a Zoho Writer template in bulk, producing either a single combined document or a separate document per record.


Merge Data: Provide exactly one of merge_data, merge_data_csv_content, merge_data_json_content, merge_data_csv_url, or merge_data_json_url.

Endpoints

OAuth Scope

ZohoWriter.documentEditor.ALLWorkDrive.files.ALLWorkDrive.organization.ALLWorkDrive.workspace.ALLZohoWriter.merge.ALLCopied!

Request Example

cURL
cURL
Deluge
Copied!
curl --request POST \
  --url https://www.zohoapis.com/writer/api/v1/templates/a1b2c3d4e5f6g7h8i9/bulkmerge \
  --header 'Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52' \
  --header 'content-type: multipart/form-data' \
  -F 'output_settings={
  "format": "pdf",
  "filename": "NDA_Agreement"
}' \
  -F 'merge_data={
  "data": [
    {
      "customer_name": "John Miller",
      "customer_email_address": "john.miller@zylker.com",
      "invoice_number": "INV-2026-045",
      "items": [
        {
          "items.item_code": "SKU-1001",
          "items.item_name": "Aria Smartwatch S2",
          "items.item_images": [
            "https://workdrive.zoho.com/external/sample-image-id-1/download?directDownload=True",
            "https://workdrive.zoho.com/external/sample-image-id-2/download?directDownload=True"
          ],
          "items.item_replacement": "Yes"
        }
      ]
    }
  ]
}' \
  -F 'merge_data_csv_content=@file_path' \
  -F 'merge_data_json_content=@file_path' \
  -F 'merge_data_csv_url=https://zylker.com/merge-data.csv' \
  -F 'merge_data_json_url=https://zylker.com/merge-data.json' \
  -F 'webhook_info={
  "url": "https://zylker.com/writer/bulkmerge-callback",
  "timeout": 60000,
  "retry": 1,
  "expiry_date": 0,
  "context": "string"
}' \
  -F 'sign_service_name=docusign' \
  -F 'test_mode=true'

Path Parameters

template_idstring(Required)

The unique identifier of the Zoho Writer template.

Request Body

multipart/form-data
output_settingsJSON Object(Optional)

Controls the file format, name, and access protection of the merged document.

Hide Sub-Attributes
formatstring(Optional)

The file format in which the merged document is downloaded.

Allowed Values :
Show Values
zdocCopied!
pdfCopied!
docxCopied!
Copied!Copy all as JSON Array
Default Value :pdfpdfCopied!
filenamestring(Optional)

A name (without file extension) for the merged document. The appropriate extension is appended automatically based on format.

Maximum Length :255255Copied!
passwordstring(Optional)

An optional password to protect the merged document. Applicable only for docx and pdf formats.

merge_tostring(Optional)

separatedoc merges each record into a separate document. singledoc merges all records into a single document.

Allowed Values :
Show Values
separatedocCopied!
singledocCopied!
Copied!Copy all as JSON Array
Default Value :singledocsingledocCopied!
restricted_accessJSON Object(Optional)

Applies permission-based restrictions to the merged document. When present, both password and permissions are required. Applies only when format is pdf; ignored for other formats.

Hide Sub-Attributes
passwordstring(Required)

The password required to override the applied document restrictions.

Maximum Length :255255Copied!
permissionsarray(Required)

The list of actions to restrict in the merged document. document.copy restricts copying content, document.print restricts printing, document.edit restricts editing, and document.fill restricts filling form fields. Any action not listed remains unrestricted.

merge_dataJSON Object(Optional)

Inline merge data as a JSON object. Must contain a data key whose value is either a single record (JSON object) or a JSON array of records, each record being a key-value map matching the template's merge fields. For a subform field, use the subform's name as the key, mapped to an array of row objects; each row's keys follow the <subform_name>.<field_name> convention (e.g. items.item_code).

Hide Sub-Attributes
dataJSON Array(Required)

Records used to populate the template merge fields. A single record may also be supplied as a JSON object instead of an array.

Hide Sub-Attributes
merge_data_csv_contentbinary(Optional)

A CSV file uploaded in the request body, up to 2 MB. Each row represents one merge record. Supported formats: csv.

merge_data_json_contentbinary(Optional)

A JSON file uploaded in the request body, up to 2 MB. Must contain an array of merge records. Supported formats: json.

merge_data_csv_urluri(Optional)

A publicly accessible URL pointing to a CSV file of merge records, up to 2 MB. Supported formats: csv.

merge_data_json_urluri(Optional)

A publicly accessible URL pointing to a JSON file of merge records, up to 2 MB. Supported formats: json.

webhook_infoJSON Object(Optional)

Configuration for a webhook invoked when the bulk merge job completes.

Hide Sub-Attributes
urluri(Optional)

The URL to which the merge status and document information are sent.

Maximum Length :255255Copied!
timeoutinteger(Optional)

The timeout in milliseconds for the webhook request.

Default Value :6000060000Copied!
Minimum Value :11Copied!
Maximum Value :120000120000Copied!
retryinteger(Optional)

The number of retry attempts if the webhook delivery fails.

Default Value :11Copied!
Minimum Value :00Copied!
Maximum Value :44Copied!
expiry_datelong(Optional)

Epoch timestamp after which the webhook is no longer invoked.

contextstring(Optional)

Arbitrary context data echoed back in the webhook payload.

Maximum Length :10001000Copied!
sign_service_namestring(Optional)

The third-party e-signature service to route the merged document through for signing. When omitted, Zoho Sign is used.

Allowed Values :
Show Values
zohosignCopied!
adobesignCopied!
docusignCopied!
Copied!Copy all as JSON Array
test_modeboolean(Optional)

When true, the merge runs without consuming credit points. The output document will include a watermark. Limited to 50 merges per day per organization.

Body Parameters

Copied!
// Note: payload contains multiple type attributes

// type: object
output_settings = {
  "format": "pdf",
  "filename": "NDA_Agreement"
}

// type: object
merge_data = {
  "data": [
    {
      "customer_name": "John Miller",
      "customer_email_address": "john.miller@zylker.com",
      "invoice_number": "INV-2026-045",
      "items": [
        {
          "items.item_code": "SKU-1001",
          "items.item_name": "Aria Smartwatch S2",
          "items.item_images": [
            "https://workdrive.zoho.com/external/sample-image-id-1/download?directDownload=True",
            "https://workdrive.zoho.com/external/sample-image-id-2/download?directDownload=True"
          ],
          "items.item_replacement": "Yes"
        }
      ]
    }
  ]
}

// type: file
merge_data_csv_content = <file>

// type: file
merge_data_json_content = <file>

// type: string(uri)
merge_data_csv_url = https://zylker.com/merge-data.csv

// type: string(uri)
merge_data_json_url = https://zylker.com/merge-data.json

// type: object
webhook_info = {
  "url": "https://zylker.com/writer/bulkmerge-callback",
  "timeout": 60000,
  "retry": 1,
  "expiry_date": 0,
  "context": "string"
}

// type: string
sign_service_name = docusign

// type: boolean
test_mode = true
Show full

Response Example

200
Copied!
  {
    "merge_report_data_url": "https://writer.zoho.com/writer/api/v1/merge/job/0tq5n465132106580437abe99b6f56f2b0c85/data",
    "merge_report_url": "https://writer.zoho.com/writer/v1/mailmerge/job/0tq5n465132106580437abe99b6f56f2b0c85",
    "records": [
      {
        "data": {
          "name": "Amelia",
          "email": "amelia@zylker.com"
        },
        "status": "inprogress"
      }
    ],
    "status": "inprogress"
  }
                
Show full