> ## Documentation Index
> Fetch the complete documentation index at: https://docs.case.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Annotate Templates

> Populate fields in DOCX templates with dynamic data

Populate fields inside a DOCX template using [SuperDoc](https://docs.superdoc.dev/getting-started/introduction) annotations. Create a template once with placeholder fields, then generate customized documents by providing field values.

## Usage

<CodeGroup>
  ```bash title="cURL" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  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
  ```

  ```bash title="CLI" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  casedev superdoc annotate \
    --file-url "https://example.com/document.pdf"
  ```

  ```typescript title="Typescript" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  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'
  });
  ```

  ```python title="Python" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  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'
  )
  ```

  ```go title="Go" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  result, _ := client.Superdoc.V1.Annotate(ctx, casedev.SuperdocV1AnnotateParams{
  	FileURL: casedev.F("https://example.com/document.pdf"),
  })
  ```
</CodeGroup>

## 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

<CodeGroup>
  ```bash title="cURL" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  # 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
  ```

  ```bash title="CLI" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  casedev superdoc annotate
  ```

  ```typescript title="Typescript" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  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);
  ```

  ```python title="Python" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  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'
  )
  ```

  ```go title="Go" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  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),
  })
  ```
</CodeGroup>

### Add signature to document

<CodeGroup>
  ```bash title="cURL" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  # 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
  ```

  ```bash title="CLI" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  casedev superdoc annotate
  ```

  ```typescript title="Typescript" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  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'
  });
  ```

  ```python title="Python" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  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'
  )
  ```

  ```go title="Go" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  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),
  })
  ```
</CodeGroup>

### 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`:

<CodeGroup>
  ```bash title="cURL" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  # 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" }
      ]
    }'
  ```

  ```bash title="CLI" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  casedev superdoc annotate
  ```

  ```typescript title="Typescript" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  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' }
    ]
  });
  ```

  ```python title="Python" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  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'}
      ]
  )
  ```

  ```go title="Go" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  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")},
  	}),
  })
  ```
</CodeGroup>

## 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](https://docs.superdoc.dev/getting-started/introduction) 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

<Info>
  See [SuperDoc's documentation](https://docs.superdoc.dev/getting-started/introduction) for details on adding annotation fields to your templates.
</Info>