Build API workflows

Use Build API workflows to combine document generation, conversion, editing, optimization, security, and final output settings in a single request. The /build endpoint is the main workflow endpoint for Nutrient DWS Processor API.

A Build API request includes three main sections:

parts — The input documents, HTML files, blank pages, or page ranges used to assemble the output.
actions — Optional operations applied after the parts are assembled, such as OCR, watermarking, rotation, redaction, annotation import, or flattening.
output — Optional final output settings, such as output format, passwords, permissions, PDF/A, PDF/UA, optimization, or linearization.

For all task-specific endpoints and guides, refer to the tools and APIs guide.

Basic Build API request

The following example uploads a PDF and returns it as result.pdf.

Shell

Run this request to send a basic Build API request:

curl -X POST https://api.nutrient.io/build \
  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
  -F document=@document.pdf \
  -F 'instructions={
    "parts": [
      {
        "file": "document"
      }
    ]
  }' \
  -o result.pdf

HTTP

Send this multipart request to upload a PDF and return it as a PDF:

POST /build HTTP/1.1
Host: api.nutrient.io
Authorization: Bearer <your_api_key_here>
Content-Type: multipart/form-data

instructions={
  "parts": [
    {
      "file": "document"
    }
  ]
}

Use multipart requests for local files

Use multipart/form-data when uploading local files. The file field names must match the names referenced in the instructions object.

Run this request to upload and assemble local files:

curl -X POST https://api.nutrient.io/build \
  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
  -F cover=@cover.pdf \
  -F body=@body.pdf \
  -F appendix=@appendix.pdf \
  -F 'instructions={
    "parts": [
      { "file": "cover" },
      { "file": "body" },
      { "file": "appendix" }
    ]
  }' \
  -o packet.pdf

In this example, the multipart field names are cover, body, and appendix, and parts[].file uses the same names.

Use JSON requests for remote files

Use application/json when all input files are available from remote URLs. In this mode, pass each remote file with file.url.

Run this request to assemble remote files:

curl -X POST https://api.nutrient.io/build \
  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parts": [
      {
        "file": {
          "url": "https://example.com/cover.pdf"
        }
      },
      {
        "file": {
          "url": "https://example.com/body.pdf"
        }
      }
    ]
  }' \
  -o packet.pdf

Understand parts

The parts array defines what goes into the output document. Nutrient DWS Processor API assembles parts in order.

Common part types include:

File parts — Existing PDFs, Office files, images, emails, and other supported input files.
HTML parts — HTML files used for PDF generation.
New page parts — Blank pages inserted into the output.
Page ranges — Selected pages from an input file.

File part

Use a file part to include an input document in the output:

{
  "parts": [
    {
      "file": "document"
    }
  ]
}

Page range

Page indexes are zero-based. Negative values count from the end of the document. The end value is inclusive.

Use a page range to include selected pages from an input document:

{
  "parts": [
    {
      "file": "document",
      "pages": {
        "start": 0,
        "end": 2
      }
    }
  ]
}

This includes pages zero, one, and two.

Blank page part

Use a blank page part to insert a new page into the output:

{
  "parts": [
    {
      "page": "new",
      "pageCount": 1,
      "layout": {
        "size": "Letter"
      }
    }
  ]
}

HTML part

Use an HTML part to generate PDF pages from HTML and related assets:

{
  "parts": [
    {
      "html": "index.html",
      "assets": ["style.css", "logo.svg"]
    }
  ]
}

Understand actions

The actions array defines operations applied after Nutrient DWS Processor API assembles the parts. Actions run in the order specified.

Common actions include:

ocr — Make scans searchable.
watermark — Add text or image watermarks.
rotate — Rotate pages.
createRedactions and applyRedactions — Create and apply redactions.
applyInstantJson — Import Instant JSON annotations or form field values.
applyXfdf — Import XML Forms Data Format (XFDF) annotations.
flatten — Flatten annotations and form fields into page content.

The following example rotates the assembled document and then adds a watermark:

{
  "parts": [
    {
      "file": "document"
    }
  ],
  "actions": [
    {
      "type": "rotate",
      "rotateBy": 90
    },
    {
      "type": "watermark",
      "text": "REVIEW",
      "width": "50%",
      "height": "20%",
      "opacity": 0.3,
      "rotation": 45
    }
  ]
}

Understand output

The output object controls the final artifact. If you omit it, typical PDF workflows return PDF output by default.

Common output types include:

pdf — Standard PDF output.
pdfa — PDF/A archival output.
pdfua — PDF/UA accessibility output.
image — Rendered image output.
docx, xlsx, pptx — Office output.
html — HTML output.
markdown — Markdown output.
json-content — JSON content extraction output.

The following example converts a PDF to DOCX:

{
  "parts": [
    {
      "file": "document"
    }
  ],
  "output": {
    "type": "docx"
  }
}

The following example produces an optimized and linearized PDF:

{
  "parts": [
    {
      "file": "document"
    }
  ],
  "output": {
    "type": "pdf",
    "optimize": {
      "mrcCompression": true,
      "imageOptimizationQuality": 2,
      "linearize": true
    }
  }
}

Workflow: Merge, watermark, and protect a PDF

This workflow merges multiple PDFs, adds a watermark, and protects the final PDF with passwords and permissions.

Use this instructions object to merge, watermark, and protect a PDF:

{
  "parts": [
    {
      "file": "cover"
    },
    {
      "file": "body"
    },
    {
      "file": "appendix"
    }
  ],
  "actions": [
    {
      "type": "watermark",
      "text": "CONFIDENTIAL",
      "width": "50%",
      "height": "20%",
      "opacity": 0.3,
      "rotation": 45
    }
  ],
  "output": {
    "type": "pdf",
    "owner_password": "owner-password",
    "user_password": "user-password",
    "user_permissions": ["printing"]
  }
}

Workflow: Scan to searchable PDF

This workflow runs optical character recognition (OCR) on a scanned PDF to create a searchable output PDF.

Use this instructions object to run OCR on a scanned PDF:

{
  "parts": [
    {
      "file": "scan"
    }
  ],
  "actions": [
    {
      "type": "ocr",
      "language": "english"
    }
  ]
}

For multilingual documents, pass an array of OCR languages:

{
  "parts": [
    {
      "file": "scan"
    }
  ],
  "actions": [
    {
      "type": "ocr",
      "language": ["english", "german", "french"]
    }
  ]
}

Workflow: Fill, flatten, and prepare for signing

This workflow applies Instant JSON form values, flattens the result, and returns a final PDF that you can sign in a later step.

Use this instructions object to fill and flatten a form:

{
  "parts": [
    {
      "file": "form"
    }
  ],
  "actions": [
    {
      "type": "applyInstantJson",
      "file": "form_filling.json"
    },
    {
      "type": "flatten"
    }
  ]
}

To cryptographically sign the output, send the resulting PDF to the /sign endpoint. Signing should be the final step in a workflow.

Workflow: HTML report to PDF/A

This workflow generates a PDF from HTML and produces PDF/A output for archival use.

Use this instructions object to generate PDF/A from HTML:

{
  "parts": [
    {
      "html": "index.html",
      "assets": ["style.css", "logo.svg"]
    }
  ],
  "output": {
    "type": "pdfa",
    "conformance": "pdfa-2a",
    "vectorization": true,
    "rasterization": true
  }
}

Treat PDF/A as an archival target. Validate final artifacts with your required compliance checker when compliance is contractual.

Workflow: Web delivery PDF

This workflow prepares a final PDF for web delivery with compression and linearization.

Use this instructions object to prepare a PDF for web delivery:

{
  "parts": [
    {
      "file": "document"
    }
  ],
  "output": {
    "type": "pdf",
    "optimize": {
      "mrcCompression": true,
      "imageOptimizationQuality": 2,
      "linearize": true
    }
  }
}

Publish linearized PDFs from a server or object storage service that supports HTTP byte-range requests.

Workflow ordering recommendations

Order matters in multistep workflows. Use these general rules:

Assemble first — Merge files, add blank pages, delete pages, duplicate pages, or reorder pages before finalizing the document.
OCR early — Run OCR before text extraction, redaction by text, or downstream text conversion when the source is scanned.
Import and fill before flattening — Apply Instant JSON or XFDF before flattening.
Redact before signing — Redaction changes document content and should happen before signing.
Optimize and linearize near the end — These are delivery-stage operations.
Sign last — Treat digitally signed PDFs as final artifacts. Modifying a signed PDF can invalidate the signature or show post-signing changes.

Analyze a Build API request

Use the /analyze_build endpoint to estimate the credit cost of a Build API request without executing it. The analysis request is free of charge.

Run this request to analyze a Build API request:

curl -X POST https://api.nutrient.io/analyze_build \
  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parts": [
      {
        "file": {
          "url": "https://example.com/document.pdf"
        },
        "content_type": "application/pdf"
      }
    ],
    "output": {
      "type": "docx"
    }
  }'

When you use /analyze_build, provide content_type for remote file parts when possible so the endpoint can identify conversion features accurately. For more details, refer to the analyze Build API guide.

Reference

A Build API request uses the BuildInstructions object:

type BuildInstructions = {
  parts: Part[],
  actions?: BuildAction[],
  output?: BuildOutput,
};

type Part = FilePart | HTMLPart | NewPagePart;

type FilePart = {
  file: string | { url: string },
  password?: string,
  pages?: {
    start?: number,
    end?: number,
  },
};

type HTMLPart = {
  html: string | { url: string },
  assets?: Array<string | { url: string }>,
  layout?: object,
};

type NewPagePart = {
  page: "new",
  pageCount?: number,
  layout?: object,
};

Refer to the build document endpoint API reference to run document processing workflows with parts, actions, and output options.
Refer to the analyze a build request endpoint API reference to estimate Build API credit usage without executing the workflow.
Refer to the digitally sign a PDF file endpoint API reference to apply a cryptographic digital signature after Build API processing.

Refer to the analyze Build API guide.
Refer to the PDF merge API guide.
Refer to the PDF split API guide.
Refer to the PDF page manipulation API guide.
Refer to the PDF OCR API guide.
Refer to the PDF watermark API guide.
Refer to the redaction API guide.
Refer to the PDF form filling API guide.
Refer to the PDF optimization API guide.
Refer to the PDF digital signature API guide.
Refer to the tools and APIs guide.

Build API workflows

Basic Build API request

Shell

HTTP

Use multipart requests for local files

Use JSON requests for remote files

Understand parts

File part

Page range

Blank page part

HTML part

Understand actions

Understand output

Workflow: Merge, watermark, and protect a PDF

Workflow: Scan to searchable PDF

Workflow: Fill, flatten, and prepare for signing

Workflow: HTML report to PDF/A

Workflow: Web delivery PDF

Workflow ordering recommendations

Analyze a Build API request

Reference

Was this helpful?

Help us improve

Thank you for your feedback!

Something went wrong. Please try again or let us know.

Build API workflows

Basic Build API request

Shell

HTTP

Use multipart requests for local files

Use JSON requests for remote files

Understand parts

File part

Page range

Blank page part

HTML part

Understand actions

Understand output

Workflow: Merge, watermark, and protect a PDF

Workflow: Scan to searchable PDF

Workflow: Fill, flatten, and prepare for signing

Workflow: HTML report to PDF/A

Workflow: Web delivery PDF

Workflow ordering recommendations

Analyze a Build API request

Reference

Related API reference operations

Related guides

Was this helpful?

Help us improve

Thank you for your feedback!

Something went wrong. Please try again or let us know.