Merge and Share Fillable Link

Merges data into a Zoho Writer document template and generates pre-filled fillable links for each record. The 'Merge and Share Fillable Link' output option must be configured in the template settings before using this API.

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

Endpoint

post https://www.zohoapis.com/writer/api/v1/documents/{document_id}/merge/sharetofill

Copy full URL

OAuth Scope

ZohoWriter.documentEditor.ALL, ZohoWriter.merge.ALL, WorkDrive.files.ALLCopied!

curl --request POST \
  --url https://www.zohoapis.com/writer/api/v1/documents/a1b2c3d4e5f6g7h8i9/merge/sharetofill \
  --header 'Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52' \
  --header 'content-type: multipart/form-data' \
  -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 'record_id=4876000000123456' \
  -F 'webhook_info={
  "url": "https://zylker.com/writer/sharetofill-callback",
  "retry": 2,
  "timeout": 30000
}' \
  -F 'test_mode=true'


    headersMap = Map();
    headersMap.put("Accept", "application/json");

    list_of_text=List();
    list_of_text.add({"paramName":"merge_data","content":"[object Object]","stringPart":"true"});
    file=invokeurl
    [
      url : "public fileURL link"
      type : GET
    ];
    list_of_text.add({"paramName":"merge_data_csv_content","content":file,"stringPart":"false"});
    file_2=invokeurl
    [
      url : "public fileURL link"
      type : GET
    ];
    list_of_text.add({"paramName":"merge_data_json_content","content":file_2,"stringPart":"false"});
    list_of_text.add({"paramName":"merge_data_csv_url","content":"https://zylker.com/merge-data.csv","stringPart":"true"});
    list_of_text.add({"paramName":"merge_data_json_url","content":"https://zylker.com/merge-data.json","stringPart":"true"});
    list_of_text.add({"paramName":"record_id","content":"4876000000123456","stringPart":"true"});
    list_of_text.add({"paramName":"webhook_info","content":"[object Object]","stringPart":"true"});
    list_of_text.add({"paramName":"test_mode","content":"true","stringPart":"true"});

    response = invokeUrl
    [
        url: "https://www.zohoapis.com/writer/api/v1/documents/{document_id}/merge/sharetofill"
        type: POST
        headers: headersMap
        files: list_of_text
        connection: connection_name
    ]

    info response;

Path Parameters

document_idstring(Required)

The unique identifier of the Zoho Writer document template.

Example

a1b2c3d4e5f6g7h8i9

Request Body

multipart/form-data

merge_dataJSON Object(Optional)

Inline merge data as a JSON object. Must contain a data key whose value is a JSON array of records, each 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).

Example

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

Hide Sub-Attributes

dataarray[object](Required)

Array of records used to populate the template merge fields.

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.

Example

https://zylker.com/merge-data.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.

Example

https://zylker.com/merge-data.json

record_idstring(Optional)

A record identifier from Zoho CRM, Zoho Creator, or Bigin. When provided, the API fetches merge data internally from the respective service.

Example

4876000000123456

Maximum Length :25Copied!

webhook_infoJSON Object(Optional)

Configures a callback URL to receive the merge status and document details after the merge operation completes.

Example

{
  "url": "https://zylker.com/writer/sharetofill-callback",
  "retry": 2,
  "timeout": 30000
}

Hide Sub-Attributes

urluri(Optional)

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

Example

https://zylker.com/writer/sharetofill-callback

Maximum Length :255Copied!

retryinteger(Optional)

The number of retry attempts if the webhook delivery fails.

Default Value :0Copied!

Minimum Value :0Copied!

Maximum Value :4Copied!

timeoutinteger(Optional)

The timeout in milliseconds for the webhook request.

Default Value :120000Copied!

Minimum Value :1Copied!

Maximum Value :120000Copied!

expiry_datelong(Optional)

The expiry timestamp, in epoch milliseconds, after which the webhook URL is no longer valid.

Example

1798761599000

contextstring(Optional)

Arbitrary data that is echoed back in the webhook callback payload.

Example

order-ref-12345

Maximum Length :1000Copied!

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.

Example

true

// Note: payload contains multiple type attributes

// 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: string
record_id = 4876000000123456

// type: object
webhook_info = {
  "url": "https://zylker.com/writer/sharetofill-callback",
  "retry": 2,
  "timeout": 30000
}

// type: boolean
test_mode = true

▼ Show full

  {
    "merge_report_data_url": "https://writer.zoho.com/writer/api/v1/merge/job/ba9cb8b6d826e05e26fd03c391dc4baa674281f9895988caf8420630887b5902/data",
    "merge_report_url": "https://writer.zoho.com/writer/v1/mailmerge/job/ba9cb8b6d826e05e26fd03c391dc4baa674281f9895988caf8420630887b5902",
    "records": [
      {
        "data": {
          "name": "Amelia",
          "email": "amelia@zylker.com"
        },
        "fillable_link": "https://writer.zoho.com/writer/open/ponazfea04477109f4681a831e7177d96bc40/fill",
        "status": "inprogress"
      }
    ],
    "status": "success"
  }

▼ Show full