# POST /documentprocessing/document/merge

> Merge a JSON data array into a Base64 DOCX, DOC, RTF or TX template with MergeSettings and returnFormat, and get the created documents as Base64 strings.

- **Product:** DS Server
- **Section:** Documentation
- **Kind:** Endpoint
- **Path:** DS Server > API Reference > Web API > DocumentProcessing > /document/merge > POST /documentprocessing/document/merge
- **2376 words**
- **Web URL:** https://docs.textcontrol.com/ds-server/reference/web-api/documentprocessing/document-merge/post/
- **LLMs URL:** https://docs.textcontrol.com/ds-server/reference/web-api/documentprocessing/document-merge/post/llms.txt
- **LLMs-Full URL:** https://docs.textcontrol.com/ds-server/reference/web-api/documentprocessing/document-merge/post/llms-full.txt

---

`POST` `https://example.com/documentprocessing/document/merge`

### Description

Merges and returns a compatible uploaded template with hierarchical JSON data.

### Examples

The following sample merges JSON data into a given template.

```bash
# Request:
curl --location --request POST 'https://trial.dsserver.io/documentprocessing/document/merge?returnFormat=PDF' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer GphAd1R0npJM9OuX2y9mUa4cfqPMOg6p' \
    --data-raw '{
        "mergeData": [
                {
                    "Id": "1",
                    "Name": "Peter",
                    "LastName": "Jackson",
                    "EMail": "peter@jackson.com",
                    "OrderItems": [
                        {
                            "Id": "1",
                            "Qty": "5",
                            "Product": "TX Spell .NET"
                        },
                        {
                            "Id": "2",
                            "Qty": "1",
                            "Product": "TX Barcode .NET"
                        },
                        {
                            "Id": "3",
                            "Qty": "3",
                            "Product": "TX Text Control .NET"
                        }
                    ]
                },
                {
                    "Id": "2",
                    "Name": "Jack",
                    "LastName": "Peterson",
                    "EMail": "jack@peterson.com",
                    "OrderItems": [
                        {
                            "Id": "1",
                            "Qty": "2",
                            "Product": "TX Spell .NET"
                        },
                        {
                            "Id": "2",
                            "Qty": "1",
                            "Product": "TX Text Control .NET"
                        }
                    ]
                }
            ],
            "template": "CAcBAA4AAAAAA[..]="
    }'

# Result:
[
    "JVBERi0xLjQNJeLjz9MNMSAwIG9iago8PAovVH[..]"
]
```

### Authorization

This endpoint supports the OAuth authorization method. DS Server checks the access token only when OAuth is enabled in the admin portal (see [Enable OAuth](https://docs.textcontrol.com/ds-server/administration/oauth/llms-full.txt)). With OAuth disabled, the default of a new installation, the endpoint accepts requests without a token.

DS Server implements OAuth as the authorization method. Two flows are supported:

- Authorization Code
- Client Credentials

To use the *Client Credentials* flow, switch on **Allow “Client Credentials” grant type** in the security profile (see [OAuth Grant Types](https://docs.textcontrol.com/ds-server/administration/oauth-grant-types/llms-full.txt)).

In both cases, a valid access token returned from the OAuth endpoints must be passed in a *Bearer* **Authorization Header**, as a **Query Parameter** or in a **Cookie**.

#### Authorization Header

| Header field | Description |
|---|---|
| Authorization | A Bearer authorization header (also called token authentication) contains the OAuth access token. The authorization method and a space i.e. "Bearer " is then put before your valid access token. For example: `Authorization: Bearer 4796E23054E64BC773CACBCAF24AD179DE9A3` |

#### Query Parameter

| Query parameter | Description |
|---|---|
| access\_token | The access token is passed directly in the endpoint URL as a query string. For example: `?access_token=4796E23054E64BC773CACBCAF24AD179DE9A3` |

#### Cookie

| Cookie | Description |
|---|---|
| access\_token | The access token is passed in a cookie named `access_token`. For example: `Cookie: access_token=4796E23054E64BC773CACBCAF24AD179DE9A3` |

### Request Parameters

| Name | Type | Value | Optional |
|---|---|---|---|
| returnFormat | String | A string that specifies the format of the created document. Possible values are: "PDF", "PDFA", "RTF", "DOC", "DOCX", "HTML", "TX" and "TXT" (plain text). **Default value is "PDF".** | yes |
| append | Boolean | Specifies whether the documents should be appended to one resulting document when more than 1 data row is passed. **Default value is true.** | yes |

### Request Payload

| Type | Value |
|---|---|
| MergeBody | The object contains the merge data as a JSON array and, optionally, a template encoded as a Base64 string and a MergeSettings object. |

#### MergeBody

| Name | Type | Value | Optional |
|---|---|---|---|
| mergeData | Array | The data source for the merge process as a JSON array of objects. | no, unless mergeDataJson is set |
| mergeDataJson | String | The merge data as a string that contains JSON, instead of `mergeData`. The .NET client sends `MergeBody.MergeDataJson` in this field. | yes |
| template | Base64 encoded string | The template encoded as a Base64 string. Supported formats are RTF, DOC, DOCX and TX. | yes |
| mergeSettings | MergeSettings | Optional merge settings to specify merge properties and document properties such as title and author. | yes |

#### MergeSettings

| Name | Type | Value | Optional |
|---|---|---|---|
| removeEmptyFields | Boolean | Specifies whether empty fields should be removed from the template or not. **Default value is true.** | yes |
| removeEmptyBlocks | Boolean | Specifies whether the content of empty merge blocks should be removed from the template or not. **Default value is true.** | yes |
| removeEmptyImages | Boolean | Specifies whether images which don't have merge data should be removed from the template or not. **Default value is false.** | yes |
| removeEmptyLines | Boolean | Specifies whether lines should be removed that contain only empty fields and no other content. **Default value is false.** | yes |
| removeTrailingWhitespace | Boolean | Specifies whether trailing whitespace should be removed before saving a document. **Default value is true.** | yes |
| mergeHtml | Boolean | Specifies whether field data can contain formatted Html content or not. HTML content must be enclosed in an <html> tag element. Only active in the Merge endpoint. **Default value is false.** | yes |
| author | String | Sets the document's author. | yes |
| creationDate | DateTime (String) | Sets the document's creation date which will be saved in the document. | yes |
| lastModificationDate | DateTime (String) | Sets the date the document is last modified. | yes |
| creatorApplication | String | Sets the application, which has created the document. | yes |
| documentSubject | String | Sets the document's subject string which will be saved in the document. PDF limitation: The length is limited to 2000 characters. | yes |
| documentTitle | String | Sets the document's title that will be saved in the document. PDF limitation: The length is limited to 2000 characters. | yes |
| userPassword | String | Specifies the password for the user to open the document. | yes |
| culture | String | Specifies the culture for the merge process for date and currency values. It must be a culture name such as "fr-FR" for French or "de-DE" for German. **Default value is "en-US".** | yes |
| formFieldMergeType | Number | Specifies in which manner form fields are treated during the merge process. Possible values are: 0 = None (Form fields are not merged at all), 1 = Preselect (Form field content is preselected when possible. Form fields not associated with a data table column are unaffected) and 2 = Replace (Form fields are replaced with database content. Empty form fields are removed according to property MergeSettings.removeEmptyFields). Pass the number; a name such as "Replace" is refused with 400. **Default value is 0 (None).** | yes |
| dataSourceCulture | String | Provides a way to specify the culture which is used when parsing date and currency values from the data source in case of formatting problems (e. g. "fr-FR" or "de-DE"). If this property is not provided, **the default is the server language.** | yes |
| mergeCulture | String | Provides a way to specify the target culture which is used when formatting date and currency values during the merge process in case of formatting problems (e. g. "fr-FR" or "de-DE"). If this property is null, **the default is the server language.** | yes |
| formattingPrinter | String | Specifies the name of a printer the text dimensions and capabilities of which are used to format the document. | yes |

### Success Response

| Status | Description |
|---|---|
| 200 | On success, the HTTP status code in the response header is 200 (OK). The response body contains an array of the created documents encoded as Base64 encoded strings. |

### Error Response

| Status | Description |
|---|---|
| 401 | A 401 (Unauthorized) with an empty body is returned, if OAuth is enabled and the request has no valid access token. |
| 400 | A 400 (Bad Request) is returned, if the body can't be read as a MergeBody object or a query parameter has a value of the wrong type, for example `append=abc`. The body is a problem details object (`application/problem+json`) with the title "One or more validation errors occurred." and the message per field in `errors`. This check comes before the license check. |
| 415 | A 415 (Unsupported Media Type) is returned, if the `Content-Type` header of a request with a body is not `application/json`. |
| 405 | A 405 (Method Not Allowed) with an empty body and the header `Allow: POST` is returned for any other HTTP method, for example `GET`. |
| 400 | A 400 (Bad Request) is returned, if no data is found in the MergeBody object or no template is uploaded. |
| 400 | A 400 (Bad Request) is returned, if DS Server is not licensed or the license is invalid. On a server that is not registered, the body is the plain text `DS Server is not registered.` (`text/plain`). DS Server checks the license before the parameter values, but after it has read the body and the typed query parameters. |
| 400 | A 400 (Bad Request) is returned, if the uploaded template is not valid. |

---

## Nearby

- **Previous:** [/documentprocessing/document/merge](https://docs.textcontrol.com/ds-server/reference/web-api/documentprocessing/document-merge/llms-full.txt)
- **Next:** [/documentprocessing/document/findandreplace](https://docs.textcontrol.com/ds-server/reference/web-api/documentprocessing/document-findandreplace/llms-full.txt)