Skip to content
Build a Doc
Home Documentation Support
This documentation is currently in preview, therefore subject to change.

Merge Word Documents

Inserts one .doc/.docx file into another using the chosen method and returns the merged file.

Parameters

NameTypeRequiredDescription
Source DocumentFile contentYesWord document to insert (e.g. output of a “Get file content” action from SharePoint or OneDrive).
Destination DocumentFile contentYesWord document to insert into.
Merge MethodStringYesDetermines how documents are merged. Options: Append, ReplaceBookmark, ReplaceText.
Merge LocationStringNoRequired when using ReplaceBookmark or ReplaceText. Provide the bookmark name or text marker to replace.

Returns

NameTypeDescription
File contentString (base64‑encoded)Base64‑encoded bytes of the merged Word document, ready for downstream actions (e.g., file creation or storage).

Troubleshooting

Click to expand common errors and fixes

Missing, Truncated or Invalid Input Documents

Cause:
Source or destination payload is empty, truncated, or not a valid Word file.

Fix:

  • Provide the full .doc / .docx binary or base64 for both documents.
  • Verify each file opens locally to confirm it is not corrupted.

Unsupported or Misspelt Merge Method

Cause:
Merge Method value is invalid or mistyped.

Fix:

  • Use exactly Append, ReplaceBookmark, or ReplaceText (case sensitive).
  • Correct typos and retry.

Merge Location Missing When Required

Cause:
ReplaceBookmark or ReplaceText selected but no Merge Location provided.

Fix:

  • Supply the exact bookmark name or text marker to replace.
  • Confirm it matches the destination document exactly.

Bookmark Not Found for ReplaceBookmark

Cause:
Destination document does not contain the specified bookmark, or the bookmark name differs (case or spacing).

Fix:

  • Confirm the bookmark exists and use the exact bookmark name.
  • Avoid hidden or temporary bookmarks, or those inside protected regions.

Text Marker Not Found for ReplaceText

Cause:
The exact text marker or placeholder does not exist in the destination document (mismatch in whitespace, case, or punctuation).

Fix:

  • Use the exact marker string.

Formatting, Sections or Pagination Change After Merge

Cause:
Source and destination use different section breaks, styles, or direct formatting - insertion may introduce unexpected section or format changes.

Fix:

  • Normalise section breaks and styles before merging.
  • Reapply the desired style after merge.
  • If appending, ensure section break rules are explicit (e.g. new section or continuous).

Style Name Collisions or Style Inheritance Issues

Cause:
Source and destination define styles with the same names but different definitions - content adopts unexpected styling.

Fix:

  • Harmonise style names (ensure style names and definitions match on both docs) or remap styles in the source document before merge.
  • Optionally perform a post-merge style normalisation pass.

Fields, Cross-References or Table of Contents Not Updated

Cause:
Fields (TOC, cross-references) still reference old indices or require updating after structural changes.

Fix:

  • Update fields and TOC after merging (manual refresh or automated update).
  • Note: some field updates may require opening the document in an editor to recalculate.

Document Protected / Read-Only Prevents Merge

Cause:
Destination or source is write-protected, restricted, or open with exclusive lock.

Fix:

  • Use an unprotected copy.
  • Ensure no locks prevent modification before merging.

Output Corrupted or Fails to Open

Cause:
Returned payload truncated, encoding error, or merge failed mid-write.

Fix:

  • Confirm the returned base64 string decodes correctly and the file opens.
  • Reproduce with minimal documents to determine whether truncation is consistent.

Large-Document Performance, Timeouts or Memory Limits

Cause:
Very large documents, many embedded objects, or complex structures exceed processing limits.

Fix:

  • Merge in smaller batches.
  • Reduce embedded asset sizes.
  • Test with representative samples to determine safe limits.

Merge Logic Doesn’t Match Expectations (Order, Numbering, References)

Cause:
Append vs insertion semantics or section indexing may lead to different ordering than expected.

Fix:

  • Verify the chosen method (Append vs Replace*) and test on a small sample to confirm resulting structure.
  • Adjust merge location or pre-process documents as needed.

Generic Runtime or Transient Error

Cause:
Malformed inputs, intermittent engine error, or unexpected internal state.

Fix:

  • Reproduce with minimal source and destination documents and a single merge method.
  • Validate inputs and retry to rule out transient failures.

Quick Checklist

  • Source Document and Destination Document are full .doc / .docx binaries (not paths or URLs).
  • Merge Method is exactly Append, ReplaceBookmark, or ReplaceText.
  • If using ReplaceBookmark or ReplaceText, Merge Location matches the destination’s bookmark name or exact marker string.
  • Test the merge with small sample documents before running on production files.
  • Reconcile styles or section breaks, or reapply the desired master or format after merging.
  • Update fields, TOC, and cross-references in the merged document as needed.
  • Ensure documents are not write-protected or open with exclusive locks.
  • If output is corrupted, reproduce with minimal redacted documents and the exact merge parameters - those inputs are required to isolate the cause.