Endpoint /documentprocessing/document/merge

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

POST

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

Examples

The following sample merges JSON data into a given template.

HTTP

# Request:
curl --location --request POST 'https://trial.dsserver.io/documentprocessing/document/merge?returnFormat=TX' \
    --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[..]"
]

# Request:
curl --location --request POST 'https://trial.dsserver.io/documentprocessing/document/merge?returnFormat=TX' \
    --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:

OAuth

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

Authorization Code
Client Credentials

In order to use the Client Credentials flow, this method must be explicitly enabled in the admin portal of DS Server.

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

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

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" and "TX". 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 datasource as a JSON data object and optionally, a template encoded as a Base64 string and a object.

MergeBody

Name	Type	Value	Optional
mergeData	JSON object	The datasource for the merge process as a JSON array.	no
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 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 the Language Culture Name that can be found in this list. For French use "fr-FR", for German "de-DE". Default value is "en-US".	yes
formFieldMergeType	Number	Specifies in which manner form fields are treated during the merge process. Possible values are: 0 Default value is 0 (None).rged at all), 1 Default value is 0 (None).t is preselected when possible. Form fields not associated with a data table column are unaffected) and 2 Default value is 0 (None).laced with database content. Empty form fields are removed according to property MergeSettings.removeEmptyFields). 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) is returned, if the user is not authorized.
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.
400	A 400 (Bad Request) is returned, if the uploaded template is not valid.