---
title: "Annotate"
method: POST
path: "/v1/annotate"
tags: ["Documents"]
---

# Annotate

`POST /v1/annotate`

Populate fields inside a DOCX template using SuperDoc annotations.

Send a JSON request body with:
- `document`: object containing either `base64` or `url`
- `fields`: array of field objects (id/group, type, value, optional options)

> **Note:** Each field requires either `id` or `group`:
> - **id**: Targets a single specific field in the template
> - **group**: Targets multiple fields with the same group identifier

The response returns the annotated DOCX/PDF file as a base64 data URI.

## Example Request

```json
{
  "document": {
    "url": "https://example.com/template.docx"
  },
  "fields": [
    {
      "id": "customer_name",
      "type": "text",
      "value": "John Doe"
    },
    {
      "id": "author",
      "type": "image",
      "value": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
      "options": {
        "dimensions": {
          "width": 200,
          "height": 100
        }
      }
    }
  ]
}
```

Alternative using base64 document input:
```json
{
  "document": {
    "base64": "UEsDBBQAAAAIAL+H..."
  },
  "fields": [
    {
      "id": "title",
      "type": "text",
      "value": "Annual Report 2024"
    }
  ]
}
```

Using group to populate multiple fields:
```json
{
  "document": {
    "url": "https://example.com/template.docx"
  },
  "fields": [
    {
      "group": "company_logo",
      "type": "image",
      "value": "https://example.com/logo.png"
    }
  ]
}
```

## Query parameters

- `to` 'docx' | 'pdf'

## Request body

- AnnotateRequest
  - `document` object, required — DOCX input provided as either base64 or URL
  - `fields` object[], required — Field entries containing id/group, type, value, and optional options
    - `id/group` string, required — Field identifier. Use `id` to target a single specific field in the template, or use `group` to populate multiple fields with the same group identifier. Only one is required.
    - `value` union, required — Value to populate the field with. String for text/image/signature fields, array of arrays for table type
      - string
      - array[]
        - string[]
    - `type` 'text' | 'image' | 'signature' | 'table', required — Type of field being populated
    - `options` object — Optional configuration for field rendering. **Options by field type:** | Field Type | Supported Options | |------------|------------------| | `text` | `keepTextNodeStyles` | | `image` | `dimensions` | | `signature` | `dimensions`, `arcElement`, `topLabel`, `bottomLabel` | | `table` | `copyRowStyle` |
      - `keepTextNodeStyles` boolean — For text fields: Whether to keep the existing text node styles when replacing content. Defaults to true.
      - `copyRowStyle` boolean — For table fields: Copy the style from the template row to populated rows
      - `dimensions` object — For image/signature fields: Specify the dimensions of the rendered element
        - `width` string — Width in pixels
        - `height` string — Height in pixels
      - `arcElement` object — For signature fields: Styling for the signature arc element
        - `color` string — Hex color code for the arc
      - `topLabel` object — For signature fields: Styling for the top label
        - `color` string — Hex color code for the top label text
      - `bottomLabel` object — For signature fields: Styling and content for the bottom label
        - `color` string — Hex color code for the bottom label text
        - `text` string — Custom text for the bottom label

## Response `200`

Annotated DOCX output encoded as a base64 data URI

- object — Annotated DOCX output encoded as a base64 data URI
  - `document` object, required
    - `base64` string, required — Data URI containing the annotated file contents
    - `contentType` string — Content type of the annotated file

## Other responses

- `400` — Standard error format used across all API endpoints
- `401` — Standard error format used across all API endpoints
- `500` — Standard error format used across all API endpoints

---

[API](https://skmtc.dev/superdoc-dev/apis/superdoc-api.md) · [All operations](https://skmtc.dev/superdoc-dev/apis/superdoc-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/superdoc-dev/superdoc-api/revisions/869ccb471697/schema)