> ## Documentation Index > Fetch the complete documentation index at: https://superdoc-caio-pizzol-docs-ai-core-preset.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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 ```json { "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: ```json { "document": { "base64": "UEsDBBQAAAAIAL+H..." }, "fields": [ { "id": "title", "type": "text", "value": "Annual Report 2024" } ] } ``` Using group to populate multiple fields: ```json { "document": { "url": "https://example.com/template.docx" }, "fields": [ { "group": "company_logo", "type": "image", "value": "https://example.com/logo.png" } ] } ``` ## OpenAPI ````yaml /openapi.json post /v1/annotate openapi: 3.0.3 info: title: SuperDoc API version: 0.9.0 description: >- ## Quick Start 1 - **Register**: https://api.superdoc.dev/v1/auth/register?email=you@email.com 2 - **Verify**: Check email, then https://api.superdoc.dev/v1/auth/verify?email=you@email.com&code=123456 3 - **Convert** ```bash curl -X POST https://api.superdoc.dev/v1/convert?from=docx \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "file=@document.docx" \ -o converted.pdf ``` Or use our Playground: https://api.superdoc.dev/docs/#tag/documents/post/v1/convert That's it! Your DOCX is now a PDF. --- [Status](https://status.superdoc.dev) • [GitHub](https://github.com/superdoc-dev/superdoc) contact: name: Support email: api@superdoc.dev url: https://superdoc.dev/contact-us license: name: Commercial url: https://superdoc.dev servers: - url: https://api.superdoc.dev description: Production security: [] tags: - name: Documents description: Document conversion and transformation - name: Authentication description: Registration and API key management - name: System description: Health and service information paths: /v1/annotate: post: tags: - Documents summary: Annotate description: >- 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 ```json { "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: ```json { "document": { "base64": "UEsDBBQAAAAIAL+H..." }, "fields": [ { "id": "title", "type": "text", "value": "Annual Report 2024" } ] } ``` Using group to populate multiple fields: ```json { "document": { "url": "https://example.com/template.docx" }, "fields": [ { "group": "company_logo", "type": "image", "value": "https://example.com/logo.png" } ] } ``` operationId: annotateDocument parameters: - schema: type: string enum: - docx - pdf in: query name: to required: false description: Output format for the annotated document (defaults to docx) requestBody: content: application/json: schema: $ref: '#/components/schemas/AnnotateRequest' examples: text-field: summary: Text field value: document: url: https://example.com/template.docx fields: - id: customer_name type: text value: John Doe image-field: summary: Image field with dimensions value: document: base64: UEsDBBQAAAAIAL+H... fields: - id: author_photo type: image value: https://example.com/image.jpg options: dimensions: width: '180' height: '250' signature-field: summary: Signature field with styling value: document: url: https://example.com/contract.docx fields: - id: client_signature type: signature value: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA... options: dimensions: width: '150' height: '80' arcElement: color: '#3bc0f1' topLabel: color: '#002fff' bottomLabel: color: '#ff0000' text: 'ip: 192.168.0.1' table-field: summary: Table field with data value: document: url: https://example.com/report.docx fields: - id: invoice_items type: table value: - - SuperDoc - Frontend - - SuperDoc Services - Backend options: copyRowStyle: true group-field: summary: Group field affecting multiple elements value: document: url: https://example.com/template.docx fields: - group: company_logo type: image value: https://example.com/logo.png options: dimensions: width: '150' height: '150' - group: footer_text type: text value: © 2024 Acme Corporation. All rights reserved. mixed-fields: summary: Multiple field types value: document: url: https://example.com/template.docx fields: - group: company_name type: text value: Acme Corporation - id: logo type: image value: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA... options: dimensions: width: '200' height: '100' - id: items_table type: table value: - - Product A - $100 - - Product B - $200 options: copyRowStyle: true required: true responses: '200': description: Annotated DOCX output encoded as a base64 data URI content: application/json: schema: description: Annotated DOCX output encoded as a base64 data URI type: object required: - document additionalProperties: false properties: document: type: object required: - base64 additionalProperties: false properties: base64: type: string minLength: 1 description: Data URI containing the annotated file contents contentType: type: string minLength: 1 description: Content type of the annotated file '400': description: Standard error format used across all API endpoints content: application/json: schema: type: object title: Error Response description: Standard error format used across all API endpoints required: - code - error - message properties: code: type: string description: Machine-readable error code for programmatic handling example: VALIDATION_ERROR error: type: string description: HTTP error category example: Bad Request message: type: string description: Human-readable error description example: The provided document format is not supported requestId: type: string description: Unique request ID for support example: req_abc123 details: type: array description: Additional error details for validation errors items: type: object properties: field: type: string description: Field that caused the error issue: type: string description: Description of the issue example: code: INVALID_FILE_FORMAT error: Bad Request message: File is not a valid DOCX requestId: req_abc123 '401': description: Standard error format used across all API endpoints content: application/json: schema: type: object title: Error Response description: Standard error format used across all API endpoints required: - code - error - message properties: code: type: string description: Machine-readable error code for programmatic handling example: VALIDATION_ERROR error: type: string description: HTTP error category example: Bad Request message: type: string description: Human-readable error description example: The provided document format is not supported requestId: type: string description: Unique request ID for support example: req_abc123 details: type: array description: Additional error details for validation errors items: type: object properties: field: type: string description: Field that caused the error issue: type: string description: Description of the issue example: code: INVALID_FILE_FORMAT error: Bad Request message: File is not a valid DOCX requestId: req_abc123 '500': description: Standard error format used across all API endpoints content: application/json: schema: type: object title: Error Response description: Standard error format used across all API endpoints required: - code - error - message properties: code: type: string description: Machine-readable error code for programmatic handling example: VALIDATION_ERROR error: type: string description: HTTP error category example: Bad Request message: type: string description: Human-readable error description example: The provided document format is not supported requestId: type: string description: Unique request ID for support example: req_abc123 details: type: array description: Additional error details for validation errors items: type: object properties: field: type: string description: Field that caused the error issue: type: string description: Description of the issue example: code: INVALID_FILE_FORMAT error: Bad Request message: File is not a valid DOCX requestId: req_abc123 security: - apiKey: [] components: schemas: AnnotateRequest: type: object required: - document - fields additionalProperties: false properties: document: type: object description: DOCX input provided as either base64 or URL fields: type: array description: Field entries containing id/group, type, value, and optional options items: type: object required: - id/group - value - type properties: id/group: type: string description: >- Field identifier. Use `id` to target a single specific field in the template, or use `group` to populate multiple fields with the same group identifier. Only one is required. value: oneOf: - type: string - type: array items: type: array items: type: string description: >- Value to populate the field with. String for text/image/signature fields, array of arrays for table type type: type: string enum: - text - image - signature - table description: Type of field being populated options: type: object description: >- Optional configuration for field rendering. **Options by field type:** | Field Type | Supported Options | |------------|------------------| | `text` | `keepTextNodeStyles` | | `image` | `dimensions` | | `signature` | `dimensions`, `arcElement`, `topLabel`, `bottomLabel` | | `table` | `copyRowStyle` | properties: keepTextNodeStyles: type: boolean description: >- For text fields: Whether to keep the existing text node styles when replacing content. Defaults to true. default: true copyRowStyle: type: boolean description: >- For table fields: Copy the style from the template row to populated rows dimensions: type: object description: >- For image/signature fields: Specify the dimensions of the rendered element properties: width: type: string description: Width in pixels example: '180' height: type: string description: Height in pixels example: '250' arcElement: type: object description: >- For signature fields: Styling for the signature arc element properties: color: type: string description: Hex color code for the arc example: '#3bc0f1' topLabel: type: object description: 'For signature fields: Styling for the top label' properties: color: type: string description: Hex color code for the top label text example: '#002fff' bottomLabel: type: object description: >- For signature fields: Styling and content for the bottom label properties: color: type: string description: Hex color code for the bottom label text example: '#ff0000' text: type: string description: Custom text for the bottom label example: 'ip: 192.168.0.1' securitySchemes: apiKey: type: http scheme: bearer bearerFormat: API Key description: API key authentication. Keys start with `sd_` ````