Convert Office files to PDF

This guide explains how to convert Office files to PDF using Document Engine.

Requirements

Ensure Document Engine is up and running. If you haven’t set it up yet, refer to our getting started guides, select the deployment option you prefer, and follow the instructions.

Converting an Office file from disk

To convert an Office file from disk, send a request to the /api/build endpoint, including both the Office file as input and the instructions JSON.

The default output from the /api/build endpoint is a PDF file. You can also specify other file types. Learn more about the output options in our API reference.

Terminal window
curl -X POST http://localhost:5000/api/build \
  -H "Authorization: Token token=<API token>" \
  -F 'document=@/path/to/example-document.docx' \
  -F instructions='{
  "parts": [
    {
      "file": "document"
    }
  ]
}' \
  -o result.pdf

Converting an Office file from URL

To convert an Office file from a URL, send a multipart request to the /api/build endpoint, attaching a URL pointing to the Office file:

Terminal window
curl -X POST http://localhost:5000/api/build \
  -H "Authorization: Token token=<API token>" \
  -F instructions='{
  "parts": [
    {
      "file": {
        "url": "https://www.nutrient.io/downloads/examples/paper.docx"
      }
    }
  ]
}' \
  -o result.pdf

Conversion parameters

You can customize Office file conversion by adding parameters to the parts object. These parameters work with both disk-based and URL-based conversions.

Available parameters

markup_mode

Controls how markup (comments, tracked changes) is preserved during Word document conversion.

  • Applicable to: Word documents (.doc, .docx, .odt, .rtf)
  • Supported values:
    • noMarkup (default) — Render the document as if all changes were accepted
    • original — Render the document as if all changes were rejected
    • simpleMarkup — Render with changes accepted and comments as annotations
    • allMarkup — Render with all markups visible, including redlines and comments
  • Default: noMarkup
  • Global configuration: Set the DOCX_MARKUP_MODE environment variable to change the default value

Renders headers and footers as half-transparent in the converted PDF.

  • Applicable to: Word documents (.doc, .docx, .odt, .rtf)
  • Supported values: true, false
  • Default: false
  • Global configuration: Set the HALF_TRANSPARENT_HEADER_FOOTER environment variable to change the default value

Example with conversion parameters

The following example demonstrates using conversion parameters. You can combine multiple parameters in a single request:

Terminal window
curl -X POST http://localhost:5000/api/build \
  -H "Authorization: Token token=<API token>" \
  -F 'document=@/path/to/example-document.docx' \
  -F instructions='{
  "parts": [
    {
      "file": "document",
      "markup_mode": "allMarkup",
      "half_transparent_header_footer": true
    }
  ]
}' \
  -o result.pdf

Converting spreadsheets

When converting spreadsheet files (such as XLSX or XLS), you can control whether to render the entire spreadsheet content or only the defined print area using the render_only_print_area parameter.

This Boolean parameter accepts the following values:

  • false — Render the entire spreadsheet content (default).
  • true — Render only the defined print area. If no print area is defined, the entire sheet will be rendered.
Terminal window
curl -X POST http://localhost:5000/api/build \
  -H "Authorization: Token token=<API token>" \
  -F 'document=@/path/to/spreadsheet.xlsx' \
  -F instructions='{
  "parts": [
    {
      "file": "document",
      "render_only_print_area": true
    }
  ]
}' \
  -o result.pdf