How to manage merge field IDs and subform fields when using Zoho Writer's merge APIs

How to manage merge field IDs and subform fields when using Zoho Writer's merge APIs

1. Why are merge field values not merged or replaced correctly during the merge operation?

If merge values are not properly replaced or are missing in the output document, it may be because the field values were not passed to the correct field IDs in the merge input data. Ensure the exact field IDs are used to avoid this issue.

2. How to obtain merge field IDs and use them with Merge APIs?

Option A: Get Field IDs via the Writer User Interface
  1. Open the merge template and navigate to the Automate tab in the left panel.
  2. Click on Manage Fields in the merge panel, then select Show Field ID to retrieve the exact field IDs.
  3. For subform field IDs:
    • Navigate to the Subform tab.
    • Expand the subform and click Show Field ID to view and copy the field IDs.

Main Field IDs


Subform Field IDs


Option B: Get Field IDs using APIs

Field IDs can also be retrieved programmatically using Writer's REST APIs or Deluge tasks. 

3. Why aren’t subform or multi-line field values merged correctly in PDF templates?

There is a known technical limitation in rendering or replacing subform values within repeat regions on PDF templates. We are actively working to address this limitation and improve the user experience for merging repeat regions in PDF templates.

Workaround: To ensure data populates correctly, insert a Text Box in the template and place the repeat tables or regions inside it. This will allow the data to merge as expected.


In Merge template, Subform or Related List fields are special merge fields that must be passed in the correct format for proper merging.

Steps to Map Subform Fields:
  1. In the Writer merge template, insert a subform table or repeat region using the Repeat button under Advanced Merge Fields.
  2. Retrieve the merge field IDs for the subform or related list fields as described earlier (in Question#2), and map the values in the input JSON data using the format below.
Example#1: Sample code to Merge Input Data with Subforms or Related Lists Fields via API

                  {
  "data": [
    {
      "customer_name": "Amelia",
      "customer_address": "13th Street, USA",
      "customer_email_address": "amelia@zylker.com",
      "customer_phone_number": "9876543210",
      "invoice_number": "123456",
      "items": [
        {
          "items.item_code": "123",
          "items.item_name": "Fastrack Revoltt FS1",
          "items.item_description": "Specifications",
          "items.item_replacement": "Yes"
        },
        {
          "items.item_code": "1278",
          "items.item_name": "Samsung Refridgerator",
          "items.item_description": "Specifications",
          "items.item_replacement": "Yes"
        }
      ]
    },
      {
       "customer_name": "John",
       "customer_address": "15th Street, India",
      ....
      }
  ]
   }
Example#2: Sample Code to Map Subform/Related List Fields via Deluge

If the merge record includes two subforms, such as items and repairs, use the following approach:
  • Fetch data using APIs like getRecords for integrations (e.g., CRM, Recruit, People).
  • Map the values for both main and subform fields as shown above.
dataMap = Map();
recordsData.put("customer_name": "Amelia");
recordsData.put("customer_address": "13th Street USA");
recordsData.put("customer_email_address": "amelia@zylker.com");
recordsData.put("customer_phone_number": "9876543210");
recordsData.put("invoice_number": "123456");
 
//Subform1 
itemsList = list();
itemMap = Map();
itemmap.put("items.item_code": "123");
itemmap.put("items.item_name": "Fastrack Revoltt FS1");
itemmap.put( "items.item_description": "<p><b>Specifications</b></p>");
itemmap.put("items.item_replacement": "Yes");
itemsList.add(itemmap);
 
//subform2 
repairList = list();
repairDetails = Map();
repairDetails.put("Repairs.Service_code", "R100");
repairDetails.put("Repairs.Description", "Faulty belt");
repairDetails.put("Repairs.Quantity", "5");
repairDetails.put("Repairs.Price", 10000);
repairList.add(repairDetails);
 
recordsData.put("items", itemsList);
recordsData.put("Repairs", repairList)
 
mergedata = Map();
mergedata.put("merge_data", {"data": recordsData});
//pass this merge data to respective merge api like mentioned below 
 
zoho.writer.mergeAndSend("eb4kob4cf65bb6d074af7a7de21e561119eb9", "pdf", "amelia@zylker.com", mergedata, "writer_name");
For more details, refer to the CRM Integration Guide.

NotesFor a complete guide on passing values for all merge field types, refer to the Comprehensive Merge Field Documentation.