ReportingCloud

POST /v1/document/findandreplace

Endpoint

POST https://api.reporting.cloud/v1/document/findandreplace

Description

Replaces text in a template and returns the result as a document. The request body holds pairs of a text to find and its replacement; the template is a stored one, named in templateName, or one sent in the body as a Base64 string. Every occurrence is replaced, without regard to case and also inside words. The response is the document as a Base64 string, in the format returnFormat names, PDF by default. To fill merge fields with data, use POST /v1/document/merge instead. See Find and Replace.

Warning

Document Quota. Each successful request counts 1 against the document quota. On a trial account, a test run (test=true) counts as well. Plans and Licensing lists the quota of each plan.

Examples

Request:

curl -u username:password \
  -H "Content-Type: application/json" \
  -d \
  " \
  {
    \"findAndReplaceData\": [
      [
      \"%%Test%%\",
      \"ReplacedString\"
      ]
    ],
    \"template\": null,
    \"mergeSettings\": null
  }
  " \
  -X POST "https://api.reporting.cloud/v1/document/findandreplace?templateName=replace.tx"

Results:

"JVBERi0xLjQNJeLjz9MNMSAwIG9iago8PAovVH..."

Authorization

This endpoint requires a "ReportingCloud-APIKey" or a "Basic" user authorization to access the user account, data and templates. Only one of these two methods is required.

API Keys describes how to create an API key, and Authentication explains both header forms.

ReportingCloud-APIKey

Header fieldDescription
AuthorizationRequired. A valid ReportingCloud account is required. The Authorization field is constructed as follows: An API key needs to be generated in the portal or with PUT /v1/account/apikey. The authorization method and a space, "ReportingCloud-APIKey ", is then put before the actual API key string. For example: Authorization: ReportingCloud-APIKey oMDM4MrAqL9QEOpyzupnQW5NjvCNtvE5cVDaaLqxI

Basic

Header fieldDescription
AuthorizationRequired. A valid ReportingCloud account is required. The Authorization field is constructed as follows: The user name and password are combined into a string separated by a colon, for example 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, "Basic ", is then put before the encoded string. For example: Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l

Request Parameters

NameTypeValueOptional
returnFormatStringA string that specifies the format of the created document. Possible values are: PDF, PDFA, RTF, DOC, DOCX, HTML, TXT and TX, in any letter case. The default value is PDF. PDFA requires an Extreme license.yes
templateNameStringThe name of the template in the template storage, with its file extension, in any letter case. If no template is specified, the template must be uploaded in the FindAndReplaceBody object of this request. If both are given, the template from the template storage is used and the uploaded one is ignored.yes
testBooleanSpecifies whether it is a test run or not. Created documents contain a "TEST MODE" watermark. Unlike a test run of convert or append, a test run of this endpoint is counted against the document quota of a trial account. Not possible using the Free license. The default value is false.yes

Request Payload

TypeValue
ReportingCloud FindAndReplaceBody objectThe FindAndReplaceBody object contains a JSON array of string arrays, a template encoded as a Base64 string and a ReportingCloud MergeSettings object.

FindAndReplaceBody

NameTypeValueOptional
findAndReplaceDataJSON arrayThe find and replace pair values as a JSON array of string arrays. In each pair, every occurrence of the first string, in any letter case and also inside words, is replaced by the second. If the second string is empty, the first is deleted. The find string must not be empty.no
templateBase64 encoded stringThe template encoded as a Base64 string. Supported formats are RTF, DOC, DOCX, TX, HTML, PDF, XLSX and plain text. If it is null or an empty string and no templateName is given, an empty document is returned.yes
mergeSettingsReportingCloud MergeSettings objectOptional merge settings to specify merge properties and document properties such as title and author.yes

MergeSettings

NameTypeValueOptional
removeEmptyFieldsBooleanSpecifies whether empty fields should be removed from the template or not. Has no effect on this endpoint.yes
removeEmptyBlocksBooleanSpecifies whether the content of empty merge blocks should be removed from the template or not. Has no effect on this endpoint.yes
removeEmptyImagesBooleanSpecifies whether images which don't have merge data should be removed from the template or not. The default value is false.yes
removeTrailingWhitespaceBooleanSpecifies whether trailing whitespace should be removed before saving a document. Has no effect on this endpoint.yes
mergeHtmlBooleanSpecifies whether field data can contain formatted HTML content or not. The default value is false. HTML content must be enclosed in an <html> tag element. Only active in the Merge endpoint.yes
authorStringSets the document's author.yes
creationDateDateTime (String)Sets the document's creation date which will be saved in the document.yes
lastModificationDateDateTime (String)Sets the date the document is last modified.yes
creatorApplicationStringSets the application, which has created the document.yes
documentSubjectStringSets the document's subject string which will be saved in the document.yes
documentTitleStringSets the document's title that will be saved in the document.yes
userPasswordStringSpecifies the password for the user to open the document.yes
cultureStringSpecifies the culture for the merge process for date and currency values. It must be a Language Culture Name of Microsoft's Table of Language Culture Names, Codes, and ISO Values. For French use "fr-FR", for German "de-DE". Default is English "en-US". Has no effect on this endpoint.yes

Success Response

StatusDescription
200On success, the HTTP status code in the response header is 200 (OK). The response body contains the created document encoded as a Base64 encoded string.

Error Response

StatusDescription
400A 400 (Bad Request) is returned, if no data is found in the FindAndReplaceBody object, findAndReplaceData is null, a find and replace pair has only one string, an empty find string or a null replacement, the template is left out and no templateName is given, the template is not found in the template storage or returnFormat is not one of the possible values.
403A 403 (Forbidden) is returned, if the user is not authorized, the document quota is exceeded or the return format PDFA is requested without an Extreme license.
405A 405 (Method Not Allowed) is returned, if the request uses another HTTP method than POST. The Allow header of the response names POST.
411A 411 (Length Required) is returned, if the request has neither a body nor a Content-Length header.
415A 415 (Unsupported Media Type) is returned, if the request has a body but no Content-Type header, or a Content-Type such as text/plain that the endpoint doesn't read. Send Content-Type: application/json.
500A 500 (Internal Server Error) is returned, if the request has no Authorization header, an empty one or one that is not the authorization method, a space and the credentials, or if the body is null or doesn't have the shape of a FindAndReplaceBody object, the template is not a valid Base64 string or returnFormat is empty.

Timeout Limitation. The pure processing time is limited to a maximum of 60 seconds. After this period of time, the task is canceled.

A typical document should not take more than 5 seconds. If your request takes longer, reduce the size of the template.