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

{
  "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:

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

Using group to populate multiple fields:

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

POST /v1/annotate

cURL

text-field

curl --request POST \ --url https://api.superdoc.dev/v1/annotate \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "document": { "url": "https://example.com/template.docx" }, "fields": [ { "id": "customer_name", "type": "text", "value": "John Doe" } ] } '

200

{
  "document": {
    "base64": "<string>",
    "contentType": "<string>"
  }
}

Authorizations

Authorization · string · header · required

API key authentication. Keys start with sd_

Query Parameters

to · enum<string>

Output format for the annotated document (defaults to docx)

Available options: docx, pdf

Body

application/json

document · object · required

DOCX input provided as either base64 or URL

fields · object[] · required

Field entries containing id/group, type, value, and optional options

Show child attributes

Response

200

application/json

Annotated DOCX output encoded as a base64 data URI

Annotated DOCX output encoded as a base64 data URI

document · object · required

Show child attributes