Merge Documents

transform.merge-documents combines a list of files into a single PDF run output, in the order given. Use it when one logical document arrives as several uploads (a scan split into one file per page, or a packet sent as separate PDFs and photos). Parse the merged file once and every downstream page index (Label Pages, Split, Separate Documents, Vision pageIndices) counts across all sources instead of restarting at 0 for each file. Downstream file steps take the merged PDF from file: {{ steps.merge.output.file }}. The rest of the output describes the pages.

inputs:
  - name: documents
    type: array
    items:
      type: file

steps:
  - name: merge
    type: transform.merge-documents
    with:
      files: "{{ input.documents }}"
      filename: packet.pdf

  - name: parse
    type: ai.parse-v2
    with:
      input: "{{ steps.merge.output.file }}"

  - name: label_pages
    type: ai.classify-pages
    with:
      input: "{{ steps.parse.output }}"
      labels:
        - name: signature
          description: A page carrying a signature

A single file is accepted too, so the same workflow handles one upload or many.

Accepted files

Source	How it becomes pages
PDF	Pages are copied as they are, text included. A PDF with permission restrictions (owner password) is copied as page images, so Parse reads those pages with OCR or vision. A PDF that needs a password to open fails the step.
JPEG, PNG, TIFF, WebP, GIF	One page per image, rotated by its EXIF orientation. Multi-page TIFF gives one page per frame. The page size follows the image DPI, or fits A4 when the image has none.
Word, PowerPoint, OpenDocument, RTF	Converted to PDF with LibreOffice first.

Any other type fails the step with the filename and type in the error. When a file arrives as application/octet-stream, its type is recovered from the filename extension or the file contents. At most 100 files are merged per step. All files together can be at most 256 MiB.

Mapping pages back to files

sources lists every input file in merge order with the 0-based, inclusive page range it occupies in the merged PDF. A page index from Label Pages or Vision maps back to its file by finding the range that contains it, for example in a transform.script step:

function script(sources: { filename: string; pageRange: [number, number] }[], page: number): string {
  return sources.find((s) => page >= s.pageRange[0] && page <= s.pageRange[1])?.filename ?? '';
}

Configuration

Configuration goes inside the step’s with: block.

string

required

Template expression resolving to the files to merge, in order: a file list input such as {{ input.documents }}, or a single file. PDF, images (JPEG, PNG, TIFF, WebP, GIF) and Word, PowerPoint, OpenDocument or RTF documents.

string

Filename of the merged PDF. Defaults to merged.pdf; .pdf is appended when missing.

Output

The merged PDF. Pass {{ steps.<step>.output.file }} to Parse, Vision or any other file input.

Show file properties

File ID of the merged PDF

Filename of the merged PDF

Always application/pdf

Size of the merged PDF in bytes

Total pages in the merged PDF

One entry per input file, in merge order, with the merged page range it occupies. Use it to map a merged page index back to its source file.

Show sources properties

Filename of the source file

MIME type of the source file

Pages this source contributed

[startIndex, endIndex] inclusive, 0-based page indices in the merged PDF

Get started

Concepts

Workflow steps

Guides & tutorials

Self-hosting

Changelog

Accepted files

Mapping pages back to files

Configuration

Output

​Accepted files

​Mapping pages back to files

​Configuration

​Output

Accepted files

Mapping pages back to files

Configuration

Output