DOCX Parsing API

Parse Word documents to structured JSON in milliseconds. Track changes, comments, tables, headers, footers and images are all kept, each as its own typed block.

Your DOCX Is Already Structured Data

A .docx file is a zip archive of XML files, in the Office Open XML format (OOXML). Paragraphs, styles, tables, revisions and comments are all recorded in document.xml, styles.xml and the files that link them. Many parsers convert the document to PDF or plain text first, and that structure is lost.

AILANG Parse reads the Office Open XML directly. Tracked changes keep their author and timestamp. Merged cells are marked with gridSpan (merged across columns) and vMerge (merged down rows). Comments stay attached to the text they refer to.

AILANG Parse scores 98.1% on OfficeDocBench (87 files across 11 formats, and it reads every one). Parsers that convert to PDF first score 51–62% on the same benchmark once the formats they cannot read are counted, because the conversion drops this structure. See benchmarks.

Raw Office XML vs Structured Output

Raw document.xml
<w:p>
  <w:pPr><w:pStyle w:val="Heading1"/></w:pPr>
  <w:r><w:t>Q1 Revenue</w:t></w:r>
</w:p>
<w:p>
  <w:r><w:rPr><w:b/></w:rPr>
    <w:t>Total: </w:t></w:r>
  <w:ins w:id="1" w:author="Alice"
         w:date="2026-03-15T10:30:00Z">
    <w:r><w:t>$2.4M</w:t></w:r>
  </w:ins>
  <w:del w:id="2" w:author="Alice"
         w:date="2026-03-15T10:30:00Z">
    <w:r><w:delText>$2.1M</w:delText></w:r>
  </w:del>
</w:p>
<w:tbl>
  <w:tr>
    <w:tc><w:tcPr><w:gridSpan w:val="2"/>
    </w:tcPr>
    <w:p><w:r><w:t>Region</w:t>...
  </w:tc></w:tr>
</w:tbl>
Structured output
{
  "metadata": {
    "title": "Q1 Revenue Report",
    "author": "Finance Team",
    "created": "2026-03-01T09:00:00Z"
  },
  "blocks": [
    {
      "type": "heading",
      "level": 1,
      "text": "Q1 Revenue"
    },
    {
      "type": "text",
      "text": "Total: $2.4M",
      "style": "Normal",
      "changes": [
        {
          "type": "insert",
          "author": "Alice",
          "date": "2026-03-15T10:30:00Z",
          "text": "$2.4M"
        },
        {
          "type": "delete",
          "author": "Alice",
          "date": "2026-03-15T10:30:00Z",
          "text": "$2.1M"
        }
      ]
    },
    {
      "type": "table",
      "headers": [{"text":"Region","gridSpan":2}],
      "rows": [...]
    }
  ]
}

What Gets Extracted

Paragraphs & Styles

Every paragraph keeps its style name (Heading 1, Normal, ListBullet and so on). Bold, italic, underline and font changes inside a paragraph are kept too.

Track Changes

Insertions, deletions and format changes, each with the author, the timestamp and the text before and after. You get the revision history, not only the final text. Deep dive →

Comments & Replies

Each comment comes with its author, date, the text it is attached to and any replies. Comments stay with the paragraph they refer to. Deep dive →

Tables & Merged Cells

Rows, columns and header rows, with merged cells marked by gridSpan (across columns) and vMerge (down rows). Deep dive →

Headers, Footers & Text Boxes

Headers and footers come out as separate section blocks. Text boxes (w:txbxContent) appear at the point in the text where they are anchored.

Images & Metadata

Embedded images are listed with their relationship ID, dimensions and alt text. Picture size is read from the image itself. Document metadata (title, author, created date, revision count) comes from the file's properties.

Track Changes

Track changes in a DOCX record the editing history: who changed what, when, and what the text said before. AILANG Parse returns every revision as a change with its type (insert/delete/formatChange), author, date and the affected text.

This information disappears when a document is converted to PDF. A legal team reviewing a contract needs to see that "Alice deleted net-30 and inserted net-60 on March 15th", not only the final text.

{
  "type": "text",
  "text": "Payment terms: net-60 days from invoice date.",
  "changes": [
    {"type": "delete", "author": "Alice Chen", "date": "2026-03-15T14:22:00Z", "text": "net-30"},
    {"type": "insert", "author": "Alice Chen", "date": "2026-03-15T14:22:00Z", "text": "net-60"}
  ]
}

See Track Changes extraction for the full specification.

Tables & Merged Cells

Word tables mark cells merged across columns with gridSpan and cells merged down rows with vMerge. AILANG Parse returns clean rows and columns with those merges marked on each cell. Nothing is guessed from how the table looks.

{
  "type": "table",
  "headers": [
    {"text": "Region", "gridSpan": 2},
    {"text": "Q1"},
    {"text": "Q2"}
  ],
  "rows": [
    [{"text": "EMEA"}, {"text": "UK"}, {"text": "$125K"}, {"text": "$140K"}],
    [{"text": "EMEA", "vMerge": "continue"}, {"text": "DE"}, {"text": "$98K"}, {"text": "$112K"}]
  ]
}

See Tables & Merged Cells for the full specification.

Comments

A DOCX comment is attached to a specific stretch of text, marked by w:commentRangeStart/w:commentRangeEnd. AILANG Parse returns each comment with its author, timestamp, the text it is attached to and any replies.

{
  "type": "text",
  "text": "The delivery timeline is aggressive.",
  "comments": [
    {
      "author": "Bob Martinez",
      "date": "2026-03-20T09:15:00Z",
      "text": "Can we push this to Q3?",
      "replies": [
        {"author": "Alice Chen", "date": "2026-03-20T10:02:00Z", "text": "Agreed, updated."}
      ]
    }
  ]
}

See Comment extraction for the full specification.

Use Cases

Legal Document Review

Extract redlines from contracts with the author and date of each change. Track changes show who modified which clause and when, an audit trail that a PDF does not carry. Pass the revisions to an LLM for clause-by-clause comparison.

Contract Analysis

Parse contracts into typed blocks. Headings give the clause structure, tables hold the obligations, and comments show the negotiation. Your code can find key terms, dates and parties without pattern-matching on raw text.

Regulatory Compliance

An audit trail has to show who changed what and when. Track changes give you that directly. Parse submission documents, compare revisions in code, and build compliance reports from structured data instead of manual review.

Academic Paper Processing

Extract the heading hierarchy, citation tables, figure references and reviewer comments from manuscript DOCX files. The output can go straight into reference management, plagiarism detection or automated formatting.

Document Migration

Convert DOCX archives to other formats: Markdown for docs-as-code, HTML for web publishing, Quarto for reproducible reports. Headings, tables and images survive the conversion.

AI Document Understanding

Give LLMs structured JSON instead of raw text. The model sees typed blocks (heading, table, comment) with their metadata, not one flat string, so it can reason about the document's structure as well as its content.

Want Markdown rather than JSON? Word to Markdown converts a .docx with its comments, tracked changes and list nesting kept. Only have the document as a PDF? PDF to Word turns it back into an editable .docx in your own template.

Try It

CLI

# Parse a DOCX file
docparse report.docx

# Convert DOCX to Markdown
docparse report.docx --convert output.md

# Convert DOCX to HTML
docparse report.docx --convert output.html

API

curl -X POST https://docparse.ailang.sunholo.com/api/v1/parse \
  -H "Content-Type: application/json" \
  -d '{"filepath":"sample_docx_formatting","outputFormat":"markdown","apiKey":"YOUR_API_KEY"}'

Python SDK

from ailang_parse import DocParse

client = DocParse(api_key="YOUR_API_KEY")
result = client.parse_file("contract.docx")

# Document metadata
print(result.metadata.title)
print(result.metadata.author)

# Iterate structured blocks
for block in result.blocks:
    if block.type == "table":
        print(f"Table: {len(block.rows)} rows")
    if hasattr(block, "changes") and block.changes:
        for change in block.changes:
            print(f"{change.author} {change.type}d: {change.text}")

Parse in Browser    API Reference

Frequently Asked Questions

How do I parse a DOCX file to JSON?

Send the .docx file to the AILANG Parse API or use the Python/JS/Go SDK. The parser reads Office Open XML directly and returns structured JSON with typed blocks.

Does DOCX parsing preserve track changes?

Yes. Every insertion, deletion, and format change is extracted with author, timestamp, and original vs revised text. See track changes docs.

Are comments extracted from DOCX files?

Yes. Each comment includes author, date, anchored text range, and reply threads. See comment extraction docs.

How are tables with merged cells handled?

You get clean rows and columns, with merged cells marked by gridSpan (across columns) and vMerge (down rows).

Does AILANG Parse convert DOCX to PDF first?

No. It reads the Office Open XML directly from the .docx file. Nothing is rendered or converted to PDF, and LibreOffice is not needed. See why this matters.

What about headers, footers, and text boxes?

Headers and footers come out as separate section blocks. Text boxes (w:txbxContent) appear at the point in the text where they are anchored.

How fast is DOCX parsing?

Typical files parse in under 50ms, with no other software to install. AILANG Parse scores 98.1% on the OfficeDocBench benchmark.