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>"
  }
}

{
  "code": "INVALID_FILE_FORMAT",
  "error": "Bad Request",
  "message": "File is not a valid DOCX",
  "requestId": "req_abc123"
}

{
  "code": "INVALID_FILE_FORMAT",
  "error": "Bad Request",
  "message": "File is not a valid DOCX",
  "requestId": "req_abc123"
}

{
  "code": "INVALID_FILE_FORMAT",
  "error": "Bad Request",
  "message": "File is not a valid DOCX",
  "requestId": "req_abc123"
}

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