# Merge Fields > Name merge fields after JSON keys, use dot notation for nested objects, set numeric and date formats, list fields with templates/info, remove empty ones. - **Product:** ReportingCloud - **Section:** Documentation - **Kind:** Topic - **Path:** ReportingCloud > Mail Merge > Merge Fields - **1722 words** - **Web URL:** https://docs.textcontrol.com/reporting-cloud/mail-merge/fields/ - **LLMs URL:** https://docs.textcontrol.com/reporting-cloud/mail-merge/fields/llms.txt - **LLMs-Full URL:** https://docs.textcontrol.com/reporting-cloud/mail-merge/fields/llms-full.txt --- An invoice number, a customer's name, the total of an order: every single value in a merged document comes from a merge field. A field is found by its name, so the names in the template and in your JSON data have to agree. Read on for how fields get their values, where you insert them, how they format numbers and dates, how to list the fields of a stored template and what happens to fields the data doesn't fill. The commands below use *sample\_invoice.tx*, the demo template of every trial account, and the invoice data of [Merge Data](https://docs.textcontrol.com/reporting-cloud/mail-merge/data-sources/llms-full.txt), saved as *data.json*. ### What a Merge Field Is A merge field is a named placeholder in an MS Word compatible template. Until the template is merged, the field shows a text such as «invoice\_no»; during the merge, ReportingCloud replaces it with the value of the same name from the data. A field has more than a name. The [GET /v1/templates/info](https://docs.textcontrol.com/reporting-cloud/reference/web-api/templates/info/get/llms-full.txt) endpoint reports these properties for each field of a stored template: | Property | Content | |---|---| | `name` | The name that is matched with the data | | `text` | The text the field shows in the template, such as «invoice\_no» | | `textBefore`, `textAfter` | Text before and after the field. In the demo template, `invoice_no` has `#` before it | | `numericFormat` | A format applied to numeric values | | `dateTimeFormat` | A format applied to date and time values | | `preserveFormatting` | Whether the formatting is preserved | ### Name Fields After the Data Where a field is in the template decides where its value comes from: - **Top-level fields**, outside of any merge block, take the value of the record with the same name. The field `invoice_no` receives `"778723"` from *data.json*. - **Fields inside a merge block** take the value of the current element of the block's array. In the block `item` of the demo template, the field `qty` receives the `qty` of each line item in turn, as [Merge Blocks](https://docs.textcontrol.com/reporting-cloud/mail-merge/blocks/llms-full.txt) explains. - **Fields for a nested object** join the name of the object and the name of its value with a dot. In the sales report of [Nested Blocks](https://docs.textcontrol.com/reporting-cloud/mail-merge/nested-blocks/llms-full.txt), the field `product.name` inside the `items` block receives `name` from the `product` object of each item. The merge matches names without regard to letter case, so the key `InvoiceNumber` in the data fills a field named `invoicenumber`. Only the case is ignored: `invoice_no` and `invoiceNo` are still different names. Two tools change the case of names: - The template editor lists the names of a datasource excerpt in lowercase: an excerpt with the key `InvoiceNumber` offers the field `invoicenumber`. - The .NET SDK sends the names of your objects in camel case: the property `InvoiceNumber` is sent as `invoiceNumber`, as [Merge Data](https://docs.textcontrol.com/reporting-cloud/mail-merge/data-sources/#merge-objects-with-the-net-sdk) describes. The demo template uses lowercase names with underscores, such as `billto_name` and `item_total`, and its data uses the same names, so they read the same in the data, in the editor and in the request. ### Insert Merge Fields You add fields while you design the template: - **In the template editor** of the ReportingCloud portal, open the template with a *datasource excerpt*, sample JSON data with the structure of your real data, and choose the fields from the **Merge Field** drop-down on the **Reporting** tab. [Template Editor](https://docs.textcontrol.com/reporting-cloud/portal/template-editor/#insert-merge-fields) lists the steps, and [Template Design](https://docs.textcontrol.com/reporting-cloud/mail-merge/template-design/llms-full.txt) designs an invoice this way. - **In a word processor** that saves MS Word formats, insert merge fields with the names of your data and save the template as DOCX, DOC or RTF. Upload it to the template storage or send it with the merge request, as [Overview](https://docs.textcontrol.com/reporting-cloud/mail-merge/overview/#send-the-template-with-the-request) shows. ### Format Values A field can format the value it receives. In the template editor, the options of a merge field have a numeric format, such as `C` for a currency amount, and the options of a date field list long and short date formats. A merge field stores its formats in the template, as the `numericFormat` and `dateTimeFormat` that `GET /v1/templates/info` reports, so the data contains only the values. How a formatted value looks also depends on the culture of the merge: with `de-DE`, the format `C` adds a euro sign, and with `en-US`, a dollar sign. [Culture](https://docs.textcontrol.com/reporting-cloud/mail-merge/culture/llms-full.txt) shows the field options and sets the culture of a merge. ### Check the Field Names of a Template Before you build data for a template that someone else designed, list its fields. The [GET /v1/templates/info](https://docs.textcontrol.com/reporting-cloud/reference/web-api/templates/info/get/llms-full.txt) endpoint returns the fields and blocks of a template in your template storage: ```bash curl "https://api.reporting.cloud/v1/templates/info?templateName=sample_invoice.tx" \ -H "Authorization: ReportingCloud-APIKey $REPORTINGCLOUD_API_KEY" \ -o info.json # The top-level fields jq -r '.mergeFields[].name' info.json ``` The response lists the top-level fields in `mergeFields`, each with the properties of the table above, and the merge blocks in `mergeBlocks`. The names in `mergeFields` are the names your data needs, and a template that isn't in the storage is answered with `400`. [Managing Templates](https://docs.textcontrol.com/reporting-cloud/document-processing/templates/#read-the-merge-fields-and-blocks-of-a-template) shows the complete response, and [Merge Blocks](https://docs.textcontrol.com/reporting-cloud/mail-merge/blocks/#list-the-blocks-of-a-template) prints the blocks with their fields. ### Remove or Keep Empty Fields When the data has no value for a field, the field is *empty*. The `removeEmptyFields` setting decides what happens to it: - **`true`**, the default, removes empty fields from the merged document. - **`false`** keeps them. The setting is part of the `mergeSettings` object of the request body. The following commands merge *data.json*, which has no `billto_city`, and keep the empty fields: ```bash jq '{mergeData: ., mergeSettings: {removeEmptyFields: false}}' data.json > merge.json curl -X POST "https://api.reporting.cloud/v1/document/merge?templateName=sample_invoice.tx&returnFormat=PDF&append=true" \ -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 ``` A second setting removes whole lines: `removeEmptyLines`, `false` by default, removes lines that contain only empty fields and no other content, such as an address line for which the data has no value. [Merge Settings](https://docs.textcontrol.com/reporting-cloud/mail-merge/settings/llms-full.txt) lists every setting with its default. ### Next Steps - [Merge Blocks](https://docs.textcontrol.com/reporting-cloud/mail-merge/blocks/llms-full.txt): repeat fields for each element of an array. - [Culture](https://docs.textcontrol.com/reporting-cloud/mail-merge/culture/llms-full.txt): format currencies and dates for a country. - [HTML Content](https://docs.textcontrol.com/reporting-cloud/mail-merge/html-content/llms-full.txt): merge formatted text into a field. - [Template Design](https://docs.textcontrol.com/reporting-cloud/mail-merge/template-design/llms-full.txt): insert fields in the template editor. --- ## Nearby - **Previous:** [Merge Data](https://docs.textcontrol.com/reporting-cloud/mail-merge/data-sources/llms-full.txt) - **Next:** [Merge Blocks](https://docs.textcontrol.com/reporting-cloud/mail-merge/blocks/llms-full.txt)