# SaveMergeTemplate - Advanced Documentation

## Overview

SaveMergeTemplate is the merge template engine used for Word-based merge documents (claim letters, contracts, etc.). Three things covered here are not obvious from the endpoint signature and have caused real confusion: image/signature/initial placeholder swapping, table merge fields bound to an Advanced Search, and the File.ID value in the response.

## Image, Signature, and Initial Fields

Image placeholders (including signature and initial images) are swapped by matching a data row's field name against the picture's own description (its Format > Alt Text), not the drawing wrapper's alt text:

- Primary match: the picture's own Description/Alt Text
- Fallback match: the picture's own Name if no row field matches the description

There is no distinction between a "signature" field and an "initial" field - both are plain image merge fields matched purely by name/description. Use whatever field naming convention distinguishes them (e.g. `Signature`, `Initial`) as the row field name.

**Trap:** A picture inserted in Word has two different "Alt Text" entry points - one on the drawing/wrapper level, one on the picture itself. Only the picture-level one is honored. Setting alt text via the wrong dialog silently produces no swap and no error.

PDF signature fields follow the same by-name logic: the signature field's name is matched against the row field name.

## Table Merge Fields (Advanced Search Binding)

A Word table becomes a repeating data table by setting its Table Properties > Alt Text > Description to a JSON string:

`{"AdvancedSearchID":<id>,"Type":"List"}` or `{"AdvancedSearchID":<id>,"Type":"Table"}`

- `AdvancedSearchID` is the ID of a stored Aptify Advanced Search definition. Its results supply the table's rows.
- `Type: "List"` - the entire table is treated as one template row; the table is cleared and one clone of the original first row is appended per result record.
- `Type: "Table"` - row 1 is kept as a fixed header; row 2 is the template row, cloned once per result record, and column values are matched to header cell text against the result columns by name.

"Advanced search" in a merge template refers specifically to this table-binding mechanism, not a distinct search UI or query type.

## File.ID in the Response

The response's File.ID is not populated on create and cannot be used to confirm the file attached successfully - it reads 0 regardless of whether the save succeeded. Do not rely on it for anything. If you need the file's ID, call GetMergeTemplateByID with the template's own ID instead.