# 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. ## The Me Field Source `FieldSource` is a string. The template type's `FieldSources` lists the values it accepts, and `Me` is always one of them. A `Me` field resolves at merge time to the staff person generating the document, so it needs no prompt and no extra parameter. Use it for the sender's own name, signature or initials. ## 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":,"Type":"List"}` or `{"AdvancedSearchID":,"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. ## Replacing the Template File Upload the new file with `FileService.GetUploadUrl`. Then fetch the template with `GetMergeTemplateByID`, keep its existing `File` object, set `File.StorageName` and `File.ObjectSize` to the values from the upload, and call `SaveMergeTemplate`. Sending a new `File` object instead of the fetched one fails with `Someone updated this File`.