Find and Replace

Not every template has merge fields. A contract written in Word with placeholders such as %%CustomerName%% in plain text, or a document in which one product name has to be replaced by another, can be filled with the findandreplace endpoint of the DocumentProcessing Web API. You send the document with a list of text pairs, and DS Server replaces each search text with its replacement and returns the result in the format you choose.

How Find and Replace Works

The endpoint is POST /documentprocessing/document/findandreplace. Its JSON body, the FindAndReplaceBody, has three properties:

The query parameter returnFormat sets the format of the result: PDF, PDFA, DOCX, DOC, RTF, HTML, TX or TXT, with PDF as the default. The response is the changed document as a Base64 string in a JSON string.

Every request needs an access token, as Authentication describes. The samples use the service URL http://localhost:5000 and the token in the variable TOKEN.

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 Merging Templates for templates designed with merge fields.

Replace Text With curl

template.docx contains the placeholders %%CustomerName%% and %%Date%%. The following commands replace them and create a DOCX document:

DS=http://localhost:5000
TOKEN="<access_token>"

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

curl --request POST "$DS/documentprocessing/document/findandreplace?returnFormat=DOCX" \
  --header "Authorization: Bearer $TOKEN" \
  --header "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.docx

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 DOCX document.

The pairs must be arrays of two strings. An object such as {"%%Date%%": "September 29, 2026"} is refused with 400 "One or more validation errors occurred.", with an error for $.findAndReplaceData.

Replace Text With .NET

In the package TXTextControl.DocumentServices.DocumentProcessing, the pairs are a list of KeyValuePair<string, string> in a FindAndReplaceBody:

using TXTextControl.DocumentServices.DocumentProcessing;
using TXTextControl.DocumentServices.DocumentProcessing.OAuth;

var oauthSettings = new OAuthSettings("<client ID>", "<client secret>");
var documentProcessing = new DocumentProcessing("http://localhost:5000", oauthSettings);

var findAndReplaceBody = new FindAndReplaceBody
{
    Template = await File.ReadAllBytesAsync("template.docx"),
    FindAndReplaceData = new List<KeyValuePair<string, string>>
    {
        new("%%CustomerName%%", "Peter Jackson"),
        new("%%Date%%", "September 29, 2026")
    }
};

byte[] document = await documentProcessing.FindAndReplace(findAndReplaceBody, ReturnFormat.DOCX);
await File.WriteAllBytesAsync("contract.docx", document);

The code works as follows:

• Template takes the document as a byte array; the package encodes it.
• FindAndReplaceData holds the pairs: the Key is the text to find and the Value its replacement.
• FindAndReplace returns the changed document as a byte array. The overload without a ReturnFormat takes the FindAndReplaceBody alone and creates PDF.

Set the Document Properties

mergeSettings takes the object described in Set Merge Options. Its document properties set the properties of the result: documentTitle, documentSubject, author, creatorApplication, creationDate, lastModificationDate and userPassword. The mergeHtml setting works only with the merge endpoint.

The following body creates a PDF document with a title and a password that is needed to open it:

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

In C#, set the MergeSettings property of the FindAndReplaceBody:

findAndReplaceBody.MergeSettings = new MergeSettings
{
    DocumentTitle = "Contract",
    UserPassword = "<password>"
};

Next Steps

• Merging Templates: fill templates with merge fields and repeating blocks.
• Converting Documents: convert a document without changing its text.
• Appending Documents: add the filled document to other documents.
• Errors and Status Codes: what to do when a request is refused.