/v1/document/findandreplace/
https://api.reporting.cloud/v1/document/findandreplace
Executes a find and replace on a template to create a document.
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, TXT 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 FindAndReplaceBody object of this request. |
| 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 |
|---|---|
| ReportingCloud FindAndReplaceBody object | The FindAndReplaceBody object contains a JSON array of string arrays, a template encoded as a Base64 string and a ReportingCloud MergeSettings object. |
FindAndReplaceBody
| Key | Value Type | Description |
|---|---|---|
| findAndReplaceData | JSON object | The find and replace pair values 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. |
| 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. |
| documentTitle | String | Optional. Sets the document's title that will be saved in the document. |
| 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 or the document quota is exceeded. |
400 (Bad Request) |
A 400 (Bad Request) is returned, if no data is found in the FindAndReplaceBody 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: