Skip to main content
The placeholder replacement tool lets you upload a DOCX or ODT template containing {{placeholder}} tags and replace them with dynamic values — text, images, lists, or even full table rows.

​
How it works

  1. Upload your template file (DOCX or ODT) via the file upload endpoint
  2. Upload any image files you want to use in placeholders
  3. Create a job via POST /tools/docx/replace-placeholders with the file ID and a variables object
  4. Poll the job via GET /tools/jobs/{jobId} until status is COMPLETED
  5. Download the result via GET /tools/files/{fileId}/download

​
Request body

{
  "fileId": "file-id-of-template",
  "variables": {
    "name": "John Doe",
    "company": "Acme Inc.",
    "logo": {
      "type": "image",
      "src": "file-id-of-uploaded-image",
      "width": 200,
      "height": 80
    },
    "features": {
      "type": "list",
      "items": ["Fast", "Reliable", "Secure"],
      "ordered": false
    },
    "pricing": {
      "type": "table",
      "rows": [
        { "plan": "Starter", "price": "€9/mo", "credits": "100" },
        { "plan": "Pro", "price": "€29/mo", "credits": "500" }
      ]
    }
  },
  "outputFormat": "pdf"
}

​
Top-level properties

PropertyTypeRequiredDescription
fileIdstringYesFile ID of the uploaded DOCX or ODT template.
variablesobjectYesMap of placeholder names to values. At least one variable is required.
outputFormatstringNoOutput format: "pdf", "docx", or "odt". Default: same as input format.
webhookobjectNoOptional webhook configuration for job completion notification.

​
Variable types

​
Text variable

A simple string value. In your template, use {{name}} and the text will be replaced directly. 
{
  "name": "John Doe",
  "company": "Acme Inc.",
  "date": "23.02.2026"
}
PropertyTypeDescription
(value)stringThe replacement text.

​
Image variable

Replaces a {{placeholder}} tag with an image. The image must first be uploaded via the file upload endpoint — pass the file ID as src. 
{
  "logo": {
    "type": "image",
    "src": "uploaded-file-id",
    "width": 200,
    "height": 80
  }
}
PropertyTypeRequiredDescription
typestringYesMust be "image"
srcstringYesFile ID of the uploaded image (PNG, JPEG, GIF, BMP, SVG).
widthnumberNoImage width in pixels. Default: 200.
heightnumberNoImage height in pixels. Default: 200.
captionstringNoAlt text for the image.
Upload the image via POST /tools/files/upload (the tools file upload), then use the returned id as the src value. Do not use the temporary image upload endpoint (POST /images/upload) — that is only for render jobs (JSON/Markdown rendering). The two upload endpoints use separate storage systems.

​
List variable

Replaces a {{placeholder}} tag with a formatted list — either bulleted or numbered. 
{
  "features": {
    "type": "list",
    "items": ["PDF Generation", "Template Engine", "API Access"],
    "ordered": false
  },
  "steps": {
    "type": "list",
    "items": ["Upload template", "Send variables", "Download result"],
    "ordered": true
  }
}
PropertyTypeRequiredDescription
typestringYesMust be "list"
itemsstring[]YesArray of list item strings.
orderedbooleanNotrue = numbered (1. 2. 3.), false = bulleted (default).
Lists are rendered as formatted text in the document. Each item appears on a new line with the appropriate prefix.

​
Table variable

Expands a single template row into multiple rows with dynamic data. This is the most powerful variable type — it duplicates a table row in your DOCX/ODT template for each entry in the rows array. 
{
  "pricing": {
    "type": "table",
    "rows": [
      { "plan": "Starter", "price": "€9/mo", "credits": "100" },
      { "plan": "Pro", "price": "€29/mo", "credits": "500" },
      { "plan": "Enterprise", "price": "€99/mo", "credits": "2000" }
    ]
  }
}
PropertyTypeRequiredDescription
typestringYesMust be "table"
rowsobject[]YesArray of row objects. Each object maps column names to values.

​
How to set up the template

In your DOCX or ODT file, create a real table with a header row and one data row. In each cell of the data row, use dot-notation placeholders:
PlanPriceCredits
{{pricing.plan}}{{pricing.price}}{{pricing.credits}}
The property names after the dot (plan, price, credits) must match the keys in each row object exactly.
The header row is static text — only the data row containing the {{varName.property}} placeholders is duplicated. Make sure each cell in the data row contains exactly one placeholder.

​
Output format

By default, the output format matches the input (DOCX in → DOCX out, ODT in → ODT out). Use outputFormat to convert:
ValueDescription
"docx"Microsoft Word format
"odt"OpenDocument Text format
"pdf"PDF

​
Complete example

​
1. Upload the template

curl -X POST https://api.autype.com/api/v1/dev/tools/files/upload \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@template.docx"
Response: 
{
  "id": "abc-template-id",
  "filename": "template.docx",
  "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
  "sizeBytes": 15234,
  "kind": "input",
  "sourceAction": null,
  "expiresAt": "2026-02-24T12:00:00.000Z",
  "createdAt": "2026-02-23T12:00:00.000Z"
}

​
2. Upload an image (optional)

curl -X POST https://api.autype.com/api/v1/dev/tools/files/upload \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@logo.png"
Response: 
{
  "id": "xyz-image-id",
  "filename": "logo.png",
  "mimeType": "image/png",
  "sizeBytes": 4096,
  "kind": "input",
  "sourceAction": null,
  "expiresAt": "2026-02-24T12:00:00.000Z",
  "createdAt": "2026-02-23T12:00:00.000Z"
}

​
3. Create the replacement job

curl -X POST https://api.autype.com/api/v1/dev/tools/docx/replace-placeholders \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileId": "abc-template-id",
    "variables": {
      "name": "John Doe",
      "company": "Acme Inc.",
      "logo": {
        "type": "image",
        "src": "xyz-image-id",
        "width": 200,
        "height": 80
      },
      "pricing": {
        "type": "table",
        "rows": [
          { "plan": "Starter", "price": "€9/mo", "credits": "100" },
          { "plan": "Pro", "price": "€29/mo", "credits": "500" }
        ]
      }
    },
    "outputFormat": "pdf"
  }'
Response: 
{
  "id": "job-123",
  "action": "docx.replace-placeholders",
  "status": "PENDING",
  "inputFileIds": ["abc-template-id"],
  "outputFileId": null,
  "error": null,
  "createdAt": "2026-02-23T12:00:00.000Z",
  "startedAt": null,
  "completedAt": null
}

​
4. Poll for completion

curl https://api.autype.com/api/v1/dev/tools/jobs/job-123 \
  -H "X-API-Key: YOUR_API_KEY"
Response (when completed): 
{
  "id": "job-123",
  "action": "docx.replace-placeholders",
  "status": "COMPLETED",
  "inputFileIds": ["abc-template-id"],
  "outputFileId": "output-file-id",
  "error": null,
  "metadata": {
    "replacedVariables": 4,
    "outputFormat": "pdf"
  },
  "createdAt": "2026-02-23T12:00:00.000Z",
  "startedAt": "2026-02-23T12:00:01.000Z",
  "completedAt": "2026-02-23T12:00:03.000Z"
}

​
5. Download the result

curl https://api.autype.com/api/v1/dev/tools/files/output-file-id/download \
  -H "X-API-Key: YOUR_API_KEY" \
  -o result.pdf

​
Supported file types

InputSupported MIME types
TemplateDOCX (application/vnd.openxmlformats-officedocument.wordprocessingml.document), ODT (application/vnd.oasis.opendocument.text)
ImagesPNG (image/png), JPEG (image/jpeg), GIF (image/gif), BMP (image/bmp), SVG (image/svg+xml)
For best results, use DOCX templates.