Annotate Templates

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

curl -X POST https://api.case.dev/superdoc/v1/annotate \
  -H "Authorization: Bearer sk_case_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }' \
  -o filled-contract.pdf

casedev superdoc annotate \
  --file-url "https://example.com/document.pdf"

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'
});

import casedev

client = casedev.Casedev(api_key='sk_case_YOUR_API_KEY')

document = 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'
)

result, _ := client.Superdoc.V1.Annotate(ctx, casedev.SuperdocV1AnnotateParams{
	FileURL: casedev.F("https://example.com/document.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

# CLI (via cURL - no direct CLI command)
curl -X POST https://api.case.dev/superdoc/v1/annotate \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }' \
  -o contract.pdf

casedev superdoc annotate

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);

contract = 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'
)

resp, _ := client.Superdoc.V1.Annotate(ctx, casedev.SuperdocV1AnnotateParams{
	Document: casedev.F(casedev.SuperdocV1AnnotateParamsDocument{
		URL: casedev.F("https://templates.example.com/service-agreement.docx"),
	}),
	Fields: casedev.F([]casedev.SuperdocV1AnnotateParamsField{
		{ID: casedev.F("client_name"), Type: casedev.F(casedev.SuperdocV1AnnotateParamsFieldsTypeText), Value: casedev.F("Acme Corporation")},
		{ID: casedev.F("client_address"), Type: casedev.F(casedev.SuperdocV1AnnotateParamsFieldsTypeText), Value: casedev.F("123 Main St, Suite 100")},
		{ID: casedev.F("effective_date"), Type: casedev.F(casedev.SuperdocV1AnnotateParamsFieldsTypeDate), Value: casedev.F("2025-01-15")},
		{ID: casedev.F("monthly_fee"), Type: casedev.F(casedev.SuperdocV1AnnotateParamsFieldsTypeNumber), Value: casedev.F("5000")},
		{ID: casedev.F("term_months"), Type: casedev.F(casedev.SuperdocV1AnnotateParamsFieldsTypeNumber), Value: casedev.F("12")},
	}),
	OutputFormat: casedev.F(casedev.SuperdocV1AnnotateParamsOutputFormatPdf),
})

Add signature to document

# CLI (via cURL - no direct CLI command)
curl -X POST https://api.case.dev/superdoc/v1/annotate \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }' \
  -o signed-agreement.pdf

casedev superdoc annotate

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'
});

signed = 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'
)

resp, _ := client.Superdoc.V1.Annotate(ctx, casedev.SuperdocV1AnnotateParams{
	Document: casedev.F(casedev.SuperdocV1AnnotateParamsDocument{
		URL: casedev.F("https://templates.example.com/agreement.docx"),
	}),
	Fields: casedev.F([]casedev.SuperdocV1AnnotateParamsField{
		{ID: casedev.F("signatory_name"), Type: casedev.F(casedev.SuperdocV1AnnotateParamsFieldsTypeText), Value: casedev.F("John Smith")},
		{ID: casedev.F("signature_date"), Type: casedev.F(casedev.SuperdocV1AnnotateParamsFieldsTypeDate), Value: casedev.F("2025-01-15")},
		{ID: casedev.F("signature"), Type: casedev.F(casedev.SuperdocV1AnnotateParamsFieldsTypeImage), Value: casedev.F("https://signatures.example.com/john-smith.png")},
	}),
	OutputFormat: casedev.F(casedev.SuperdocV1AnnotateParamsOutputFormatPdf),
})

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:

# CLI (via cURL - no direct CLI command)
curl -X POST https://api.case.dev/superdoc/v1/annotate \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document": { "url": "https://example.com/template.docx" },
    "fields": [
      { "group": "client_name", "type": "text", "value": "Acme Corporation" }
    ]
  }'

casedev superdoc annotate

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' }
  ]
});

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

resp, _ := client.Superdoc.V1.Annotate(ctx, casedev.SuperdocV1AnnotateParams{
	Document: casedev.F(casedev.SuperdocV1AnnotateParamsDocument{
		URL: casedev.F(templateURL),
	}),
	Fields: casedev.F([]casedev.SuperdocV1AnnotateParamsField{
		// Updates all fields tagged with "client_name" group
		{Group: casedev.F("client_name"), Type: casedev.F(casedev.SuperdocV1AnnotateParamsFieldsTypeText), Value: casedev.F("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.

​Usage

​Parameters

​Document object

​Field object

​Field types

​Response

​Examples

​Fill a contract template

​Add signature to document

​Use field groups for repeated content

​Creating templates

Usage

Parameters

Document object

Field object

Field types

Response

Examples

Fill a contract template

Add signature to document

Use field groups for repeated content

Creating templates