DOCX/ODT Placeholder Replacement

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

Upload your template file (DOCX or ODT) via the file upload endpoint
Upload any image files you want to use in placeholders
Create a job via POST /tools/docx/replace-placeholders with the file ID and a variables object
Poll the job via GET /tools/jobs/{jobId} until status is COMPLETED
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

Property	Type	Required	Description
`fileId`	string	Yes	File ID of the uploaded DOCX or ODT template.
`variables`	object	Yes	Map of placeholder names to values. At least one variable is required.
`outputFormat`	string	No	Output format: `"pdf"`, `"docx"`, or `"odt"`. Default: same as input format.
`webhook`	object	No	Optional 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"
}

Property	Type	Description
(value)	string	The 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
  }
}

Property	Type	Required	Description
`type`	string	Yes	Must be `"image"`
`src`	string	Yes	File ID of the uploaded image (PNG, JPEG, GIF, BMP, SVG).
`width`	number	No	Image width in pixels. Default: 200.
`height`	number	No	Image height in pixels. Default: 200.
`caption`	string	No	Alt 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
  }
}

Property	Type	Required	Description
`type`	string	Yes	Must be `"list"`
`items`	string[]	Yes	Array of list item strings.
`ordered`	boolean	No	`true` = 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" }
    ]
  }
}

Property	Type	Required	Description
`type`	string	Yes	Must be `"table"`
`rows`	object[]	Yes	Array 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:

Plan	Price	Credits
`{{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:

Value	Description
`"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

Input	Supported MIME types
Template	DOCX (`application/vnd.openxmlformats-officedocument.wordprocessingml.document`), ODT (`application/vnd.oasis.opendocument.text`)
Images	PNG (`image/png`), JPEG (`image/jpeg`), GIF (`image/gif`), BMP (`image/bmp`), SVG (`image/svg+xml`)

For best results, use DOCX templates.

Overview

Document JSON Syntax

Tools Guides

Images

Rendering

Bulk Rendering

Projects & Documents

Tools File Management

Tools PDF Actions

Tools Document Actions

Lens (AI)

Tools Jobs

DOCX/ODT Placeholder Replacement

How it works

Request body

Top-level properties

Variable types

Text variable

Image variable

List variable

Table variable

How to set up the template

Output format

Complete example

1. Upload the template

2. Upload an image (optional)

3. Create the replacement job

4. Poll for completion

5. Download the result

Supported file types

​How it works

​Request body

​Top-level properties

​Variable types

​Text variable

​Image variable

​List variable

​Table variable

​How to set up the template

​Output format

​Complete example

​1. Upload the template

​2. Upload an image (optional)

​3. Create the replacement job

​4. Poll for completion

​5. Download the result

​Supported file types

How it works

Request body

Top-level properties

Variable types

Text variable

Image variable

List variable

Table variable

How to set up the template

Output format

Complete example

1. Upload the template

2. Upload an image (optional)

3. Create the replacement job

4. Poll for completion

5. Download the result

Supported file types