The Merge Data JSON Object Format Explained

When merging templates with data, a JSON object contains merge data for all merge fields and merge blocks in the document. Using the language specific SDKs, the JSON object is created automatically and you don't need to know the exact expected JSON structure. For example, the .NET SDK accepts an object as data which is then transformed to the required JSON data implicitly.

Consider the following .NET class:

Now, an instance of that object is created and passed to the MergeData property of the MergeBody object:

In the MergeDocument method, the MergeBody object is simply passed as a parameter:

Internally, the wrapper is creating the expected JSON format of the complete mergeBody object:

Sample Template

The sample template, that gets copied into your template storage when creating a trial account, contains top level merge fields and a merge block that contains separate merge fields:

Top level merge fields are all fields in a template that are not part of a merge block. The complete template is repeated based on the number of records (array entries) in the merge data. Merge fields encapsulated in a merge block are repeated based on the number of merge block data rows in the JSON array. Additionally, merge blocks can be nested in unlimited levels. The following JSON data contains 1 top level record:

The data is part of an JSON array. The array contains 1 top level entry and this entry has two items in the merge block item. The following sample JSON structure contains 2 top level array entries that produces 2 resulting documents: