/v1/document/merge/
https://api.reporting.cloud/v1/document/merge
Merges and returns a compatible template from the template storage or an uploaded template with hierarchical JSON data.
This method counts against the document quota. For each successful request, the quota count is increased by 1.
Authorization
This endpoint requires a "ReportingCloud-APIKey" or a "Basic" user authorization to access the user acount, data and templates. Only one of these two methods are required.
ReportingCloud-APIKey
| Header field | Description |
|---|---|
| Authorization |
Required. A valid ReportingCloud account is required. The Authorization field is constructed as follows: An API Key needs to be generated using the portal or /v1/account/apikey endpoint. The authorization method and a space i.e. "ReportingCloud-APIKey " is then put before the actual API Key string. Sample: Authorization: ReportingCloud-APIKey oMDM4MrAqL9QEOpyzupnQW5NjvCNtvE5cVDaaLqxI |
Basic
| Header field | Description |
|---|---|
| Authorization |
Required. A valid ReportingCloud account is required. The Authorization field is constructed as follows: The username and password are combined into a string separated by a colon, e.g.: username:password. The resulting string is encoded using the RFC2045-MIME variant of Base64, except not limited to 76 char/line. The authorization method and a space i.e. "Basic " is then put before the encoded string. Sample: Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l |
Request Parameters
| Query Parameter | Value Type | Description |
|---|---|---|
| returnFormat | String | A string that specifies the format of the created document. Possible values are: PDF, PDFA, RTF, DOC, DOCX, HTML and TX. |
| templateName | String | Optional. The name of the template in the template storage. If no template is specified, the template must be uploaded in the MergeBody object of this request. |
| append | Boolean | Optional. Specifies whether the documents should be appened to one resulting document when more than 1 data row is passed. |
| test | Boolean | Optional. Specifies whether it is a test run or not. A test run is not counted against the quota and created documents contain a watermark. Not possible using the Free or Trial license. |
Request Payload
| Value Type | Description |
|---|---|
| MergeBody | The MergeBody object contains the datasource as a JSON data object and optionally, a template encoded as a Base64 string and a ReportingCloud MergeSettings object. |
MergeBody
| Key | Value Type | Description |
|---|---|---|
| mergeData | JSON object | The datasource for the merge process as a JSON array. |
| template | Base64 encoded string | Optional. The template encoded as a Base64 string. Supported formats are RTF, DOC, DOCX and TX. |
| mergeSettings | ReportingCloud MergeSettings object | Optional. Optional merge settings to specify merge properties and document properties such as title and author. |
MergeSettings
| Key | Value Type | Description |
|---|---|---|
| removeEmptyFields | Boolean | Optional. Specifies whether empty fields should be removed from the template or not. The default value is true. |
| removeEmptyBlocks | Boolean | Optional. Specifies whether the content of empty merge blocks should be removed from the template or not. The default value is true. |
| removeEmptyImages | Boolean | Optional. Specifies whether images which don't have merge data should be removed from the template or not. The default value is false. |
| removeEmptyLines | Boolean | Optional. Specifies whether lines should be removed that contain only empty fields and no other content. The default value is false. |
| removeTrailingWhitespace | Boolean | Optional. Specifies whether trailing whitespace should be removed before saving a document. The default value is true. |
| mergeHtml | Boolean | Optional. Specifies whether field data can contain formatted Html content or not. The default value is false. Html content must be enclosed in an | tag element. Only active in the Merge endpoint.
| author | String | Optional. Sets the document's author. |
| creationDate | DateTime (String) | Optional. Sets the document's creation date which will be saved in the document. |
| lastModificationDate | DateTime (String) | Optional. Sets the date the document is last modified. |
| creatorApplication | String | Optional. Sets the application, which has created the document. |
| documentSubject | String | Optional. Sets the document's subject string which will be saved in the document. PDF limitation: The length is limited to 2000 characters. |
| documentTitle | String | Optional. Sets the document's title that will be saved in the document. PDF limitation: The length is limited to 2000 characters. |
| userPassword | String | Optional. Specifies the password for the user to open the document. |
| culture | String | Optional. 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 is English "en-US". |
Success Response
| Return Value | Description |
|---|---|
200 (OK) |
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
| Return Value | Description |
|---|---|
403 (Forbidden) |
A 403 (Forbidden) is returned, if the user is not authorized, the document quota is exceeded or more than 2 concurrent requests came in from the same account. |
400 (Bad Request) |
A 400 (Bad Request) is returned, if no data is found in the MergeBody object, no template is uploaded or template is not found in the template storage. |
The pure processing time is limited to a maximum of 60 seconds. After this period of time, the task is cancelled.
A typical document should not take more than 5 seconds. If your requests takes longer, please decrease the number of data rows and reduce the template size.
Sample Requests
Request:
Results:
Request:
Results:
Request:
Results:
Request:
Results:
Request:
Results: