Merge Settings

Every merge request can carry a MergeSettings object that controls how empty data is handled, how values are formatted and which properties the created documents get. All of its properties are optional, and a request without the object merges with the defaults listed below. The tables cover each property with its type, its default and its effect, and link the pages that explain a setting in depth.

The object is the mergeSettings property of the MergeBody that POST /v1/document/merge receives. Overview describes the request as a whole.

Merge Options

These properties change what the merge does with the template and the data:

A line is removed by removeEmptyLines only when nothing but empty fields is on it. Put optional values, such as a second address line, on lines of their own.

Document Properties

These properties are saved in the created documents. The reference lists no default for them:

Dates are strings in the ISO 8601 date and time format, such as "2026-10-02T09:30:00+00:00", the format the PHP SDK documents as the one the backend uses.

Send Merge Settings With the Web API

The following body merges the demo template sample_invoice.tx with a shortened invoice record, removes lines that are left empty and sets the culture and the document properties. Save it as merge.json:

{
  "mergeData": [
    {
      "invoice_no": "778723",
      "billto_name": "Joey Montana",
      "billto_companyname": "Montana, LLC",
      "billto_street": "1 Washington Dr",
      "billto_city": "Charlotte",
      "billto_zip": "27878"
    }
  ],
  "mergeSettings": {
    "removeEmptyLines": true,
    "culture": "en-US",
    "author": "Text Control, LLC",
    "documentTitle": "Invoice 778723",
    "creationDate": "2026-10-02T09:30:00+00:00"
  }
}

Send it like any other merge request:

curl -X POST "https://api.reporting.cloud/v1/document/merge?templateName=sample_invoice.tx&returnFormat=PDF" \
  -H "Authorization: ReportingCloud-APIKey $REPORTINGCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @merge.json \
  -o result.json

jq -r '.[0]' result.json | base64 -d > invoice.pdf

Properties you leave out, or set to null, keep their defaults. Instead of the object, the body can also carry "mergeSettings": null, as the HTTP sample of the reference does.

Set Merge Settings in the SDKs

The SDKs map the object to a class or an array of their own. They don't all offer every property:

The differences matter in these cases:

• Java and Ruby. A MergeSettings object of these SDKs sends all five Boolean options and sets removeEmptyImages to true unless you change it, unlike the Web API's default of false. Without such an object, a request carries no merge settings, and the Web API's defaults apply. Neither SDK has culture or removeEmptyLines; send such a request to the Web API directly.
• PHP. The SDK takes creation_date and last_modification_date as Unix timestamps and converts them. It accepts only the culture names of the list that Culture links. A key it doesn't know, such as remove_empty_lines, is ignored.
• .NET. Culture is a string in the builds of the package for .NET Standard and .NET Core and a System.Globalization.CultureInfo in the build for .NET Framework 4.5.

The following C# program sets the options of the curl sample with the .NET SDK:

using TXTextControl.ReportingCloud;

ReportingCloud rc = new ReportingCloud(Environment.GetEnvironmentVariable("REPORTINGCLOUD_API_KEY"));

MergeBody mergeBody = new MergeBody
{
    MergeData = new[] { new { invoice_no = "778723", billto_name = "Joey Montana" } },
    MergeSettings = new MergeSettings
    {
        RemoveEmptyLines = true,
        Culture = "en-US",
        Author = "Text Control, LLC",
        DocumentTitle = "Invoice 778723",
        CreationDate = DateTime.UtcNow
    }
};

List<byte[]> documents = rc.MergeDocument(mergeBody, "sample_invoice.tx", ReturnFormat.PDF);
File.WriteAllBytes("invoice.pdf", documents[0]);

Settings of Other Endpoints

Two other endpoints take settings objects of their own:

• Find and replace. POST /v1/document/findandreplace takes a MergeSettings object as well, in its FindAndReplaceBody. Its documents get the document properties, while removeEmptyFields, removeEmptyBlocks, removeTrailingWhitespace, mergeHtml and culture have no effect there, and its reference doesn't list removeEmptyLines. Find and Replace describes the endpoint.
• Appending. POST /v1/document/append takes a DocumentSettings object with the seven document properties and no merge options, as Appending Documents describes.

Related Pages

• Culture: format currency values and dates for a country.
• HTML Content: merge formatted text with mergeHtml.
• Conditional Blocks: show or remove sections with removeEmptyBlocks.
• POST /v1/document/merge: the endpoint's parameters, body and responses.