HTML to DOCX Service - Documentation

Quick Start

Send a POST request to /convert with HTML content in the request body:

curl -X POST https://your-domain.com/convert \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1>Hello World</h1><p>This is a test.</p>",
    "fileName": "my-document.docx"
  }' \
  --output my-document.docx

💡 Tip: The service automatically handles HTML tables with rowspan/colspan, applies formatting presets, and returns a ready-to-use DOCX file.

API Reference

POST /convert

Convert HTML content to DOCX format with optional formatting presets.

Request Body (JSON)

Parameter	Type	Required	Description
`html`	string	Required	HTML content to convert. Supports standard HTML tags, tables, lists, etc.
`fileName`	string	Optional	Output filename (default: "document.docx"). Extension .docx is automatically added if missing.
`formatPreset`	string	Optional	Name of formatting preset to apply (e.g., "Fusion Insure"). See Format Presets section.

Response

On success (HTTP 200), returns a DOCX file with headers:

Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Disposition: attachment; filename="[your-filename].docx"
X-Request-ID: [unique-request-id] - Use this for tracking and debugging

GET /health

Service health check. Returns status, version, and dependency checks.

GET /docs

This documentation page. Add ?format=json for JSON response.

Code Examples

cURL

curl -X POST https://your-domain.com/convert \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1>Report</h1><table><tr><th>Name</th><th>Value</th></tr><tr><td>Test</td><td>123</td></tr></table>",
    "fileName": "report.docx",
    "formatPreset": "Fusion Insure"
  }' \
  --output report.docx

JavaScript (fetch)

const response = await fetch('https://your-domain.com/convert', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    html: '<h1>My Document</h1><p>Content here</p>',
    fileName: 'output.docx',
    formatPreset: 'Fusion Insure'
  })
});

const blob = await response.blob();
const url = window.URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'output.docx';
a.click();

Python (requests)

import requests

html_content = """
<h1>Sales Report</h1>
<table>
  <tr><th>Product</th><th>Revenue</th></tr>
  <tr><td>Widget A</td><td>$1,000</td></tr>
</table>
"""

response = requests.post(
    'https://your-domain.com/convert',
    json={
        'html': html_content,
        'fileName': 'sales-report.docx',
        'formatPreset': 'Fusion Insure'
    }
)

with open('sales-report.docx', 'wb') as f:
    f.write(response.content)

Format Presets

Format presets apply consistent styling, branding, and formatting to your documents.

"Fusion Insure" Preset

Font Family:

Times New Roman

Body Font Size:

11pt

Heading Size:

14pt

Brand Color:

#00563F (Dark Green)

Secondary Color:

#44546A (Blue-Gray)

Table Header BG:

#00563F

Header Logo:

Right-aligned, 2" width

📋 What the preset does:

Adds branded header logo to all pages (right-aligned)
Styles first 4 non-empty paragraphs with brand green color
Applies consistent fonts and sizes throughout document
Formats table headers with brand colors
Sets professional margins and spacing

Features

Table Cell Merging

Automatically handles HTML rowspan and colspan attributes, creating properly merged cells in Word tables.

Custom Fonts & Colors

Apply brand-specific fonts, colors, and styling through format presets.

Header Logos

Automatically insert logos in document headers with configurable alignment and size.

Request Tracking

Every request gets a unique X-Request-ID header for debugging and log correlation.

HTML Support

Supports standard HTML: headings, paragraphs, tables, lists, bold, italic, links, and more.

Production Ready

Built with gunicorn, structured logging, health checks, and error handling.

Error Handling

HTTP 400 - Bad Request

Cause: Missing or invalid HTML content in request body.

Response: {"error": "HTML content is required in JSON body with key 'html'"}

Fix: Ensure your request body is valid JSON with an "html" key containing the HTML content.

HTTP 500 - Internal Server Error

Cause: Conversion failed due to malformed HTML, missing dependencies, or internal error.

Response: {"error": "[error message]", "request_id": "[unique-id]"}

Fix: Check the error message. Use the request_id to search logs for detailed debugging information.

Common Issues & Solutions

Issue	Solution
Table cells not merging correctly	Ensure rowspan/colspan attributes are properly set in HTML. The service processes these automatically.
Format preset not applied	Check spelling of formatPreset name (case-sensitive). Use /health endpoint to see available presets.
Special characters corrupted	Ensure HTML is properly UTF-8 encoded and special characters are HTML-encoded.
Logo not appearing in header	Check /health endpoint to verify logo asset is available. Contact admin if asset is missing.

🔍 Debugging Tips:

Every response includes an X-Request-ID header - save this for support requests
Check the /health endpoint to verify all dependencies and assets are available
Test with simple HTML first, then gradually add complexity
Use browser DevTools Network tab to inspect request/response details