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:
- Create a DOCX document in Microsoft Word or Google Docs
- Add SuperDoc annotation fields where you want dynamic content
- Upload the template to a publicly accessible URL or your storage
- Call the Annotate API with field values
See SuperDoc’s documentation for details on adding annotation fields to your templates.
