Annotate Templates

Populate fields in DOCX templates with dynamic data

Populate fields inside a DOCX template using SuperDoc annotations. Create a template once with placeholder fields, then generate customized documents by providing field values.

Usage

import Casedev from 'casedev';

const client = new Casedev({ apiKey: 'sk_case_YOUR_API_KEY' });

const document = await client.superdoc.v1.annotate({
  document: {
    url: 'https://your-bucket.s3.amazonaws.com/templates/contract.docx'
  },
  fields: [
    { id: 'client_name', type: 'text', value: 'Acme Corporation' },
    { id: 'contract_date', type: 'date', value: '2025-01-15' },
    { id: 'contract_amount', type: 'number', value: 50000 }
  ],
  output_format: 'pdf'
});

Parameters

Parameter	Type	Required	Description
document	object	Yes	Document source (see below)
fields	array	Yes	Fields to populate (see below)
output_format	string	No	Output format: docx or pdf. Default: docx

Document object

Provide either a URL or base64-encoded content:

Property	Type	Description
url	string	URL to the DOCX template
base64	string	Base64-encoded DOCX template

Field object

Property	Type	Required	Description
id	string	One of	Target field ID (for single field)
group	string	One of	Target field group (for multiple fields)
type	string	Yes	Field type: text, image, date, number
value	string/number	Yes	Value to populate
options	object	No	Additional options (e.g., image dimensions)

Field types

Type	Value Format	Use Case
text	String	Names, descriptions, addresses
number	Number	Amounts, quantities, prices
date	ISO date string	Contract dates, deadlines
image	Image URL	Signatures, logos, stamps

Response

Returns the annotated document as binary data with appropriate content type based on output_format.

Examples

Fill a contract template

const contract = await client.superdoc.v1.annotate({
  document: {
    url: 'https://templates.example.com/service-agreement.docx'
  },
  fields: [
    { id: 'client_name', type: 'text', value: 'Acme Corporation' },
    { id: 'client_address', type: 'text', value: '123 Main St, Suite 100' },
    { id: 'effective_date', type: 'date', value: '2025-01-15' },
    { id: 'monthly_fee', type: 'number', value: 5000 },
    { id: 'term_months', type: 'number', value: 12 }
  ],
  output_format: 'pdf'
});

// Send to client
res.setHeader('Content-Type', 'application/pdf');
res.setHeader('Content-Disposition', 'attachment; filename="contract.pdf"');
res.send(contract);

Add signature to document

const signed = await client.superdoc.v1.annotate({
  document: {
    url: 'https://templates.example.com/agreement.docx'
  },
  fields: [
    { id: 'signatory_name', type: 'text', value: 'John Smith' },
    { id: 'signature_date', type: 'date', value: '2025-01-15' },
    {
      id: 'signature',
      type: 'image',
      value: 'https://signatures.example.com/john-smith.png',
      options: { width: 200, height: 50 }
    }
  ],
  output_format: 'pdf'
});

Use field groups for repeated content

When your template has multiple fields with the same tag (e.g., a header and footer both showing client name), use group instead of id:

const document = await client.superdoc.v1.annotate({
  document: { url: templateUrl },
  fields: [
    // Updates all fields tagged with "client_name" group
    { group: 'client_name', type: 'text', value: 'Acme Corporation' }
  ]
});

Creating templates

To create a template for use with the Annotate API:

1. Create a DOCX document in Microsoft Word or Google Docs
2. Add SuperDoc annotation fields where you want dynamic content
3. Upload the template to a publicly accessible URL or your storage
4. Call the Annotate API with field values

See SuperDoc’s documentation for details on adding annotation fields to your templates.