Find and Replace

Some templates mark the places to fill with plain text, such as %%CustomerName%%, instead of merge fields, for example templates that come from an older application. POST /v1/document/findandreplace fills such a template without redesigning it: you send a list of text pairs, and ReportingCloud replaces every occurrence of each search text with its replacement, in the main text, the headers and footers and the text frames, and returns the result in the format you choose.

How Find and Replace Works

The endpoint is POST /v1/document/findandreplace. It takes three query parameters:

Its JSON body, the FindAndReplaceBody, has three properties:

The search ignores letter case and also finds a search text inside a word, so choose placeholders that occur nowhere else in the text, such as %%CustomerName%%. An empty replacement deletes the search text, and an empty search text is refused.

The response is the changed document as a Base64 string in a JSON string. The Web API answers 400 Bad Request when the body has no data, when neither a template nor a template name is given, or when the named template is not in the storage.

Every successful request adds one document to the document quota; Plans and Licensing lists the quota of each plan. Every request also needs the Authorization header that Authentication describes.

Find and Replace or Merge

Both endpoints fill a template with data. Which one fits depends on the template:

Use find and replace for existing documents with text placeholders, and Mail Merge for templates designed with merge fields in the template editor.

Replace Text With curl

contract.docx contains the placeholders %%CustomerName%% and %%Date%%. The following commands send the document with the replacements and save the result as contract.pdf:

# Build the FindAndReplaceBody from the document and the text pairs
jq -n \
  --rawfile template <(base64 -w 0 contract.docx) \
  '{
    template: $template,
    findAndReplaceData: [
      ["%%CustomerName%%", "Joey Montana"],
      ["%%Date%%", "October 2, 2026"]
    ]
  }' > replace.json

curl "https://api.reporting.cloud/v1/document/findandreplace?returnFormat=PDF" \
  -H "Authorization: ReportingCloud-APIKey $REPORTINGCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @replace.json \
  --output replaced.json

# Decode the Base64 string of the response
jq -r . replaced.json | base64 -d > contract.pdf

The commands work as follows:

• --rawfile template reads the Base64 string of the document into the variable $template.
• findAndReplaceData lists the pairs. The first string of each pair is the text to find, and the second is its replacement.
• jq -r . removes the quotes of the response, and base64 -d decodes the PDF.

Use a Template From the Storage

A template that you use again and again can stay in your template storage. Upload it once, in the portal or with the upload endpoint that Managing Templates describes, and name it in templateName. A stored template is RTF, DOC, DOCX or TX. The body then holds the pairs alone:

curl "https://api.reporting.cloud/v1/document/findandreplace?templateName=contract.docx&returnFormat=PDF" \
  -H "Authorization: ReportingCloud-APIKey $REPORTINGCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"findAndReplaceData": [["%%CustomerName%%", "Joey Montana"], ["%%Date%%", "October 2, 2026"]]}' \
  --output replaced.json

The template in the storage stays unchanged: the replacements apply to the document that the request returns. When a request names a stored template and also sends one in the body, the stored template is used.

Replace Text With .NET

In the .NET SDK, the NuGet package TXTextControl.ReportingCloud, the pairs are a list of string arrays in a FindAndReplaceBody:

using TXTextControl.ReportingCloud;

ReportingCloud rc = new ReportingCloud(
    Environment.GetEnvironmentVariable("REPORTINGCLOUD_API_KEY"));

FindAndReplaceBody body = new FindAndReplaceBody
{
    Template = File.ReadAllBytes("contract.docx"),
    FindAndReplaceData = new List<string[]>
    {
        new[] { "%%CustomerName%%", "Joey Montana" },
        new[] { "%%Date%%", "October 2, 2026" }
    },
    MergeSettings = new MergeSettings { DocumentTitle = "Contract" }
};

// No template name: the template travels in the body
byte[] pdf = rc.FindAndReplaceDocument(body, null, ReturnFormat.PDF);
File.WriteAllBytes("contract.pdf", pdf);

The code works as follows:

• Template takes the document as a byte array; the SDK encodes it. For a template from the storage, leave Template empty and pass the name as the second argument, rc.FindAndReplaceDocument(body, "contract.docx", ReturnFormat.PDF).
• FindAndReplaceData holds the pairs, each a string[] with the text to find and its replacement.
• MergeSettings sets the title of the result, as the next section describes.
• FindAndReplaceDocument returns the changed document as a byte array. A fourth argument, test, sends a test run. A refused request throws an ArgumentException whose message is the response body.

The PHP SDK has the same call as findAndReplaceDocument($findAndReplaceData, $returnFormat, $templateName, $templateFilename, $mergeSettings). It takes the pairs as an associative array, ['%%CustomerName%%' => 'Joey Montana'], and either a template name or the path of a template file.

Set the Document Properties

mergeSettings takes the MergeSettings object of the merge endpoint. Its document properties set the properties of the result: author, documentTitle, documentSubject, creatorApplication, creationDate, lastModificationDate and userPassword, the password a user must enter to open the document. The setting mergeHtml works with the merge endpoint only. Merge Settings describes every setting of the object.

The following body creates a document with a title and a password:

jq -n \
  --rawfile template <(base64 -w 0 contract.docx) \
  '{
    template: $template,
    findAndReplaceData: [["%%CustomerName%%", "Joey Montana"]],
    mergeSettings: {documentTitle: "Contract", userPassword: "<password>"}
  }' > replace.json

Next Steps

• Mail Merge: fill templates with merge fields and repeating merge blocks.
• Managing Templates: upload a template to the storage and use it by name.
• Appending Documents: add the filled document to other documents.
• Errors and Status Codes: what to do when a request is refused.