Document Segmentation

Segmentation splits a PDF that holds several documents into individual documents. It finds each document's page boundaries and partition key (for example an IBAN), and each resulting document is processed separately downstream.

Overview

Segmentation splits a PDF that merges several documents (bank statements, invoices, financial forms) into individual documents. It finds the boundaries between them and creates one file per document.

Page classification only labels the pages of a single document. Segmentation creates new PDF files and keeps a link from each one to the parent file it came from.

Key Concepts

Use Cases

Result Structure

Segmentation output is returned by GET /api/v1.1/workflow-runs/{run_id} in the segmentation_result object, which holds two views of the same result. Use whichever suits your integration. No extra call is needed.

Per-section view (document grouping)

segmentation_result.sections: one entry per identified document, with the list of pages that belong to it. This is the view to use when you need each document's page range. Adjacent documents of the same type stay separate entries here (the per-page view below cannot distinguish them).

{
  "segmentation_result": {
    "sections": [
      {"section_id": "identity_document", "pages": [1], "partition_key": null},
      {"section_id": "invoice", "pages": [2, 3], "partition_key": null},
      {"section_id": "bank_details", "pages": [4], "partition_key": "FR7630004020360001026054720"}
    ],
    "pages": [
      {"page": 1, "section": "identity_document", "partition": null},
      {"page": 2, "section": "invoice", "partition": null},
      {"page": 3, "section": "invoice", "partition": null},
      {"page": 4, "section": "bank_details", "partition": "FR7630004020360001026054720"}
    ]
  }
}

Per-page view

segmentation_result.pages: a flat list with one entry per page, giving the identified section type and the partition identifier (e.g. an IBAN) when one is detected. Convenient for page-level lookups, but it does not preserve document boundaries between adjacent same-type documents; use sections for that.

The same sections shape is also available per node (with the segmenter's confidence and reasoning) on GET /api/v1.1/workflow-runs/{run_id}/node-runs/.

{
  "results": {
    "confidence": 0.96,
    "reasoning": "Page 1 is an identity document, pages 2-3 an invoice, page 4 a bank details form (RIB).",
    "sections": [
      {"section_id": "identity_document", "pages": [1], "partition_key": null},
      {"section_id": "invoice", "pages": [2, 3], "partition_key": null},
      {"section_id": "bank_details", "pages": [4], "partition_key": "FR7630004020360001026054720"}
    ],
    "pages": [
      {"page": 1, "section": "identity_document", "partition": null},
      {"page": 2, "section": "invoice", "partition": null},
      {"page": 3, "section": "invoice", "partition": null},
      {"page": 4, "section": "bank_details", "partition": "FR7630004020360001026054720"}
    ]
  }
}

Per-page fields (segmentation_result)

Per-section fields (segmentation_result.sections)

The /node-runs/ endpoint returns the same sections array per segmenter node, together with the segmenter's confidence and reasoning. See the Workflow Runs API reference for the full node object.

How It Works

Segmentation is enabled in document processing workflows. When activated, the segmenter analyzes each page of the document using AI to:

1. Classify pages: Identify the document type for each page
2. Detect boundaries: Find where one document ends and another begins
3. Identify partitions: Group pages by unique identifiers (when configured)
4. Create segments: Generate new PDF files for each identified segment
5. Route for processing: Send segments to appropriate extractors

API Configuration

When using the Workflow Runs API, the /node-runs/ endpoint returns each segmenter node with both the agent configuration used and the segmentation results.

{
  "node_type": "segmenter",
  "status": "completed",
  "agent_id": "sa_3vRt7wXp9kLm",
  "is_global_agent": false,
  "config": {
    "segmenter_name": "Bank Account Splitter",
    "custom_rules": null,
    "prompt": null,
    "sections": [
      {
        "section_id": "bank_account",
        "section_description": "Bank statement pages with transactions",
        "partition_key": "iban",
        "partition_description": "IBAN identifying the account"
      }
    ]
  },
  "results": {
    "confidence": 0.95,
    "reasoning": "All pages belong to a single account identified by its IBAN.",
    "sections": [
      {"section_id": "bank_account", "pages": [1, 2, 3], "partition_key": "FR7630004020360001026054720"}
    ],
    "pages": [
      {"page": 1, "section": "bank_account", "partition": "FR7630004020360001026054720"},
      {"page": 2, "section": "bank_account", "partition": "FR7630004020360001026054720"},
      {"page": 3, "section": "bank_account", "partition": "FR7630004020360001026054720"}
    ]
  },
  "started_at": "2024-01-15T10:30:03Z",
  "completed_at": "2024-01-15T10:30:08Z",
  "duration_ms": 5000
}

For a Global (system) Segmenter, config is null and is_global_agent is true; the results block is populated the same way.

Config Fields