Splitting Configuration

The Split API accepts a config object that controls how a document is divided into sub-documents. Only splitClassifications is required — it defines the document types the splitter can assign. Everything else is optional: use splitRules to guide where the splitter divides the document, baseProcessor and baseVersion to pick the model, advancedOptions for Excel handling, page overlap, and page ranges, and parseConfig to tune how the document is parsed before splitting.

You can pass config inline on a one-off /split call, or save it to a reusable Splitter and reference that splitter by id. Either way the configuration is identical.

For default values and the full schema, see the Create Split Run API reference.

Prefer a UI? Extend Studio lets you configure the splitter visually and export the config JSON.

Split classifications

splitClassifications

Type: array of classification objects (required)

The document types the splitter can assign to each sub-document. You must provide at least one classification, and at least one classification must have the type "other" as a catch-all. Each entry must have a unique id.

{
  "config": {
    "splitClassifications": [
      {
        "id": "loan_application",
        "type": "loan_application",
        "description": "A Uniform Residential Loan Application (Form 1003)."
      },
      {
        "id": "other",
        "type": "other",
        "description": "Any other document type."
      }
    ]
  }
}

splitClassifications[].identifierKey

Type: string

A natural-language rule describing how to extract a unique identifier for sub-documents of this type, for example "Extract the invoice number from the document header". When provided, the splitter extracts the identifier for each sub-document of that type and returns it in the split’s identifier field. It also uses the value to decide when adjacent pages belong to the same document versus a new one.

{
  "config": {
    "splitClassifications": [
      {
        "id": "invoice",
        "type": "invoice",
        "description": "An invoice or bill for goods or services.",
        "identifierKey": "Extract the invoice number from the document header"
      }
    ]
  }
}

Split rules

splitRules

Type: string

Custom rules, in natural language, that guide how the splitter divides the document — for example “Keep all pages of a signed contract together” or “Treat each new account number as a new statement.”

{
  "config": {
    "splitRules": "Keep all pages of a signed contract together in a single split."
  }
}

Base processor

baseProcessor

Type: "splitting_performance" | "splitting_light" (default: splitting_performance)

The splitting model to use.

{
  "config": {
    "baseProcessor": "splitting_performance"
  }
}

baseVersion

Type: string

The version of the selected processor to use. If not provided, the latest stable version for the selected baseProcessor is used automatically. See the Splitting Performance versions.

{
  "config": {
    "baseProcessor": "splitting_performance",
    "baseVersion": "1.5.0"
  }
}

Advanced options

advancedOptions.splitExcelDocumentsBySheetEnabled

Type: boolean (default: false)

For Excel documents, split by worksheet.

{
  "config": {
    "advancedOptions": {
      "splitExcelDocumentsBySheetEnabled": true
    }
  }
}

advancedOptions.pageOverlapEnabled

Type: boolean (default: false)

When enabled, the splitter allows page overlap so a page can occur in two adjacent splits when it carries context for both the previous and the next document.

{
  "config": {
    "advancedOptions": {
      "pageOverlapEnabled": true
    }
  }
}

advancedOptions.strictIdentifierModeEnabled

Type: boolean

When enabled, adjacent candidate sub-documents that share the same type and the same extracted identifier are merged into a single split before the splitter finalizes its boundaries.

Use it when one logical document repeats its identifier across its pages — a multi-page invoice whose invoice number appears on every page, or a loan file where each borrower’s documents carry the same borrower ID — and you want one split per identifier instead of several consecutive splits of the same document. Leave it off when the same identifier legitimately appears on documents that should stay separate, such as a statement and its remittance stub sharing an account number.

Identifiers come from the identifierKey rule on the matching classification when one is defined. Classifications without an identifierKey still get a short descriptive identifier that the splitter assigns itself, so merging can apply to them too — define identifierKey on any classification you intend to merge by, so the identifier is a stable document-level value rather than a description. Comparison ignores case and surrounding whitespace.

{
  "config": {
    "splitClassifications": [
      {
        "id": "invoice",
        "type": "invoice",
        "description": "An invoice or bill for goods or services.",
        "identifierKey": "Extract the invoice number from the document header"
      }
    ],
    "advancedOptions": {
      "strictIdentifierModeEnabled": true
    }
  }
}

advancedOptions.pageRanges

Type: Array<{ start: number, end: number }>

Restrict splitting to specific page ranges. Page numbers are 1-based and inclusive.

{
  "config": {
    "advancedOptions": {
      "pageRanges": [{ "start": 1, "end": 20 }]
    }
  }
}

Parse config

parseConfig

Type: object

Because the document is parsed before it is split, you can tune that step with parseConfig (for example, chunking and block options). See Parse Configuration for the full set of options.

{
  "config": {
    "parseConfig": {
      "chunkingStrategy": { "type": "page" }
    }
  }
}

Using a saved splitter

To reuse a configuration across runs and workflows, create a Splitter and reference it by id instead of inlining config each time. You can override specific fields per run with overrideConfig.

A splitter is a kind of processor — see that page for how saving a configuration lets you version, evaluate, and optimize it.

• Create a splitter — set up a new splitter with your configuration.
• Update a splitter — modify an existing splitter’s configuration.
• Run a splitter — execute a splitter, optionally with splitter.overrideConfig.