JSON API

Introduction

phpdocx Premium licenses include a JSON API that allows working with DOCX and PDF documents from any language or platform capable of sending and receiving JSON data. This is not a remote or hosted service. Instead, it provides the classes and methods you need to build your own REST-ready architecture, API, or microservice using a JSON-based interface.

Among its many features, the following can be highlighted:

Add new contents (text, tables, images, lists, charts...).
Create and apply new styles and customize existing ones.
Transform HTML into Word content.
Replace contents in templates.
Clone and delete blocks in templates.
Modify page layout and settings.
Format conversion (HTML, DOCX to PDF, TXT...).
DocxPath queries to manipulate existing content.
Merge and watermark documents.
Utilities for DOCX and PDF documents.
Work with WordFragments.
Performance features such as chunk mode and zip stream.
Files such as images can be added as local paths, Data URL (Uniform Resource Locator) with Base64-encoded string, or remote URLs.

All available actions and their JSON data parameters are documented in the JSON API reference.

Request structure

A JSON API request is a JSON object with the following top-level keys:

{
    "template": "string",
    "settings": object,
    "wordfragments": array,
    "actions": [
        {
            "action": "string",
            "data": object
        }
    ]
}

template (optional): The path to a DOCX template. Can be a local file path, a Base64-encoded string, or a remote URL.
settings (optional): Extra settings that apply to the entire request, such as chunkMode or streamMode.
wordfragments (optional): An array of WordFragments to be used in the request. Each WordFragment has:
- name: The name of the WordFragment.
- actions: The content of the WordFragment.
actions: An array of actions to execute sequentially. Each action has:
- action: The name of the phpdocx action to call (e.g. addText, replaceVariableByText).
- data: The JSON object containing the action parameters.

Multiple actions can be chained in a single request. They are executed in the order they appear in the actions array.

New documents

To create a new DOCX from scratch, omit the template key and add the content actions to run. For example, to add a paragraph, a list, and HTML:

{
    "actions": [
        {
            "action": "addText",
            "data": {
                "text": "Hello from the JSON API.",
                "optionsParagraph": {
                    "bold": true,
                    "font": "Arial",
                    "fontSize": 12
                }
            }
        },
        {
            "action": "addList",
            "data": {
                "values": ["Line 1", ["Line A", "Line B", "Line C"], "Line 2", "Line 3", "Line 4", "Line 5"],
                "styleType": 2
            }
        },
        {
            "action": "embedHTML",
            "data": {
                "html": "<p>This is a paragraph with <strong>bold</strong> and <em>italic</em> text.</p>"
            }
        }
    ]
}

Each action maps directly to a phpdocx method. All available actions and their JSON data parameters are documented in the JSON API reference.

Template documents

To work with an existing DOCX template, provide the template key. The template is loaded first, and then the actions are applied on top of it.

For example, to open a DOCX template and replace text variables:

{
    "template": "template.docx",
    "actions": [
        {
            "action": "replaceVariableByText",
            "data": {
                "variables": {
                    "FIRSTTEXT": "PHPDocX",
                    "MULTILINETEXT": "This is the first line.\nThis is the second line of text."
                },
                "options": {
                    "parseLineBreaks": true
                }
            }
        }
    ]
}

A template can be provided as:

A local file path:
"template": "path/to/template.docx"
A Data URL (Uniform Resource Locator) with Base64-encoded string:
"template": "data:application/vnd.openxmlformats-officedocument.wordprocessingml.document;base64,..."
A remote URL:
"template": "https://domain.com/template.docx"

Template actions include replacing variables by text, image, HTML, WordFragments...; cloning and deleting blocks; getting template variable information; and many more. All available actions and their JSON data parameters are documented in the JSON API reference.

Settings

The optional settings key accepts global options that apply to the entire request.

Available settings:

chunkMode: Improves performance and reduces memory usage when adding large tables and lists. Set to true to enable.
streamMode: Generates a DOCX stream without saving the document to the file system. Set to true to enable.
responseType: Specifies the response type for the request. Possible values are "json" and "stream".

For example, to enable chunk mode:

{
    "settings": {
        "chunkMode": true
    },
    "actions": [
        {
            "action": "addTable",
            "data": {
                "values": [
                    ["Header 1", "Header 2", "Header 3"],
                    ["Row 1 Col 1", "Row 1 Col 2", "Row 1 Col 3"],
                    ["Row 2 Col 1", "Row 2 Col 2", "Row 2 Col 3"]
                ]
            }
        }
    ]
}

Response types

The responseType setting controls how the generated file is returned by the JSON API. If omitted, the default value is "json".

When responseType is "json" (default):

The API returns a JSON string.
On success, the response includes status: "success" and a data object with:
- output: Base64-encoded generated file content.
- mime: MIME type for the generated document.
Actions that return document information append their results to data. For example:
- getDocxPathQueryInfo adds docxPathQueryInfo.
- getTemplateVariables adds templateVariables.
On error, the response includes status: "error" and a message with the error text.

Sample JSON response (success):

{
    "status": "success",
    "data": {
        "output": "UEsDBBQAAAAIA...",
        "mime": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
    },
    "message": ""
}

Sample JSON response (error):

{
    "status": "error",
    "data": {},
    "message": "Error processing JSON: Syntax error"
}

When responseType is "stream":

The API returns the generated file content directly as a binary stream string.
No JSON wrapper is returned.
Error responses are not supported in stream mode; if an error occurs, an empty string is returned.

Available actions

The JSON API covers all major phpdocx action groups:

Word contents.
Layouts.
Templates.
Format conversion.
DocxPath.
DocxUtilities.
PdfUtilities.
DocxCustomizer.
Performance.

The full reference with all JSON data schemas and code samples is available in the JSON API documentation.

WordFragments

WordFragments let you define reusable content and inject them in actions to generate new documents or replace variables in templates.

The following JSON sample illustrates how to define and use WordFragments:

{
    "wordfragments": [
        {
            "name": "wf_image",
            "actions": [
                {
                    "action": "addImage",
                    "data": {
                        "src": "image.png",
                        "scaling": 50,
                        "textWrap": 1,
                        "float": "right"
                    }
                }
            ]
        },
        {
            "name": "wf_link",
            "actions": [
                {
                    "action": "addLink",
                    "data": {
                        "text": "link to Google",
                        "options": {
                            "url": "https://www.google.com",
                            "color": "0000FF",
                            "underline": "single"
                        }
                    }
                }
            ]
        },
        {
            "name": "wf_footnote",
            "actions": [
                {
                    "action": "addFootnote",
                    "data": {
                        "textDocument": "here it is",
                        "textFootnote": "This is the footnote text."
                    }
                }
            ]
        }
    ],
    "actions": [
        {
            "action": "addText",
            "data": {
                "text": [
                    { "text": "wf_image" },
                    { "text": "I am going to write a link: ", "bold": true },
                    { "text": "wf_link" },
                    { "text": " to illustrate how to include links."},
                    { "text": " As you may see it is extremely simple to do so and it can be done with any other Word element. For example to include a footnote is also as simple as this: "},
                    { "text": "wf_footnote" },
                    { "text": " , as you may check there is a footnote at the bottom of the page.", "color": "B70000" }
                ]
            }
        }
    ]
}

WordFragments can include one or more actions.

More information

The JSON API documentation provides individual reference pages for every action, including the JSON data schema, parameter descriptions, and code samples.

In addition to this documentation, phpdocx Premium packages include many ready-to-run samples illustrating how to use all JSON API actions.