Workflow JSON Format

Technical reference for the workflow definition format.

Overview

Every workflow is stored as a JSON definition that describes a directed graph of PDF operations. You can export any workflow as a .json file and import it into another account or environment. This page documents the JSON schema so you can also create or modify workflow definitions programmatically.

Top-Level Schema

A workflow definition is a JSON object with the following fields:

Field	Type	Required	Description
name	string	No	Display name for the workflow (max 100 characters).
description	string	No	A short description of what the workflow does (max 500 characters).
category	string	No	Category label (e.g., “Conversion”, “Security”).
nodes	array	Yes	An array of node objects representing the workflow steps.
connections	array	Yes	An array of connection objects linking nodes together.

Nodes

Each node represents a single PDF operation in the workflow pipeline. Nodes are objects with the following fields:

Field	Type	Required	Description
id	string	Yes	Unique identifier for the node within this workflow (e.g., "node-1").
type	string	Yes	The operation type. Must match one of the valid operation types.
label	string	Yes	Display label shown on the canvas (e.g., "Compress PDF").
x	number	Yes	Horizontal position on the builder canvas.
y	number	Yes	Vertical position on the builder canvas.
parameters	object	No	Key-value pairs of operation-specific parameters. Omitted or empty means use defaults.

Connections

Connections define how data flows between nodes. The output of the source node is passed as input to the target node.

Field	Type	Required	Description
id	string	Yes	Unique identifier for the connection (e.g., "edge-1").
sourceId	string	Yes	The id of the source node.
targetId	string	Yes	The id of the target node.
sourcePort	string	No	Source port name (for operations with multiple outputs). Usually omitted.
targetPort	string	No	Target port name (for operations with multiple inputs). Usually omitted.

Valid Operation Types

The type field on each node must be one of the following values. These are case-sensitive and use PascalCase.

Conversion

Type	Description
ConvertToWord	PDF to Microsoft Word
ConvertToExcel	PDF to Excel spreadsheet
ConvertToPowerPoint	PDF to PowerPoint slides
ConvertToImages	PDF pages to image files
ConvertToPdfA	Convert to PDF/A compliance
ConvertToPdfX	Convert to PDF/X compliance
ConvertJpegToPdf	JPEG images to PDF
ConvertPdfColors	Convert colour space
ConvertXfaToAcroForm	XFA forms to AcroForm
OcrPdf	Recognise text in scanned PDFs

Security

Type	Description
ProtectPdf	Add password and permission restrictions
RedactPdf	Remove or mask sensitive information

Page Manipulation

Type	Description
MergePdfs	Combine multiple PDFs into one (accepts multiple inputs)
SplitPdf	Split a PDF into multiple files
ExtractPages	Extract specific pages
RemovePages	Delete selected pages
ReorganizePdf	Reorder pages
RotatePages	Rotate pages by angle
ResizePage	Change page dimensions
RemoveBlankPages	Automatically remove blank pages
ClipPdf	Crop a region from pages

Content

Type	Description
AddWatermark	Overlay text or image watermark
AddPageNumbers	Insert sequential page numbers
GenerateToc	Generate a table of contents
ConvertUrlsToLinks	Make plain-text URLs clickable
AddEmbeddedFiles	Embed files within a PDF
UpdatePdfMetadata	Edit document metadata
ApplyOpenOptions	Set initial view and layout options

Optimisation

Type	Description
CompressPdf	Reduce file size
RepairPdf	Fix corrupted PDFs
LinearizePdf	Optimise for fast web viewing
FlattenTransparencies	Flatten transparent objects
FlattenAnnotations	Burn annotations into content

Extraction

Type	Description
ExtractText	Extract text content
ExtractImages	Extract images as a ZIP
ExtractEmbeddedFiles	Retrieve embedded files
ExportFormData	Export AcroForm data
ExportXfaData	Export XFA data

Analysis

Type	Description
AnalyzePdf	Analyse structure and contents
GetPdfVersion	Get PDF specification version
GetPdfPermissions	Inspect permission settings
ReadPdfMetadata	Read document metadata
ComparePdfPages	Compare pages from two PDFs (accepts multiple inputs)

Examples

Simple two-step workflow

This workflow compresses a PDF and then adds password protection:

{
  "name": "Secure Document",
  "description": "Compress and password-protect a PDF.",
  "category": "Security",
  "nodes": [
    {
      "id": "node-1",
      "type": "CompressPdf",
      "label": "Compress PDF",
      "x": 200,
      "y": 150,
      "parameters": {}
    },
    {
      "id": "node-2",
      "type": "ProtectPdf",
      "label": "Protect PDF",
      "x": 200,
      "y": 300,
      "parameters": {}
    }
  ],
  "connections": [
    {
      "id": "edge-1",
      "sourceId": "node-1",
      "targetId": "node-2"
    }
  ]
}

Multi-step archival workflow

This workflow converts to PDF, compresses, and then converts to PDF/A for archival:

{
  "name": "Office to PDF Archive",
  "description": "Convert, compress, and archive as PDF/A.",
  "category": "Conversion",
  "nodes": [
    {
      "id": "node-1",
      "type": "ConvertJpegToPdf",
      "label": "Convert to PDF",
      "x": 200,
      "y": 150,
      "parameters": {}
    },
    {
      "id": "node-2",
      "type": "CompressPdf",
      "label": "Compress PDF",
      "x": 200,
      "y": 300,
      "parameters": {}
    },
    {
      "id": "node-3",
      "type": "ConvertToPdfA",
      "label": "Convert to PDF/A",
      "x": 200,
      "y": 450,
      "parameters": {
        "conformanceLevel": "PDF/A-2b"
      }
    }
  ],
  "connections": [
    {
      "id": "edge-1",
      "sourceId": "node-1",
      "targetId": "node-2"
    },
    {
      "id": "edge-2",
      "sourceId": "node-2",
      "targetId": "node-3"
    }
  ]
}

Import & Export

Exporting a workflow

You can export any workflow as a .json file in two ways:

• From the Workflow Builder: Click the Export button in the toolbar. You will be prompted for a name, and the file will download automatically.
• From Workflow Management: Click the Export button on any workflow or template card.

Importing a workflow

To import a workflow from a .json file:

1. Open the Workflow Builder.
2. Click the Import button in the toolbar.
3. Select a .json file from your computer.
4. The workflow loads onto the canvas. Any unrecognised operation types are skipped with a warning.
5. Review the imported workflow and click Save to store it.

Related: Workflow Builder · Managing Workflows · Workflows Overview