> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autype.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DOCX/ODT Placeholder Replacement

> Replace {{placeholder}} tags in DOCX and ODT documents with text, images, lists, and tables

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](/api-reference/developer-api/upload-a-file)
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

```json theme={null}
{
  "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](/api-reference/webhooks) for job completion notification. |

## Variable types

### Text variable

A simple string value. In your template, use `{{name}}` and the text will be replaced directly.

```json theme={null}
{
  "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`.

```json theme={null}
{
  "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.                                   |

<Info>
  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.
</Info>

### List variable

Replaces a `{{placeholder}}` tag with a formatted list — either bulleted or numbered.

```json theme={null}
{
  "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). |

<Note>
  Lists are rendered as formatted text in the document. Each item appears on a new line with the appropriate prefix.
</Note>

### 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.

```json theme={null}
{
  "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.

<Warning>
  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.
</Warning>

## 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

```bash theme={null}
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:

```json theme={null}
{
  "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)

```bash theme={null}
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:

```json theme={null}
{
  "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

```bash theme={null}
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:

```json theme={null}
{
  "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

```bash theme={null}
curl https://api.autype.com/api/v1/dev/tools/jobs/job-123 \
  -H "X-API-Key: YOUR_API_KEY"
```

Response (when completed):

```json theme={null}
{
  "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

```bash theme={null}
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`)                               |

<Note>
  For best results, use DOCX templates.
</Note>