> This page is for version v2026-02-09 (default).
> For other versions, use one of these documentation indexes:
> - v2026-02-09 (default): https://docs.extend.ai/2026-02-09/llms.txt
> - v2025-04-21: https://docs.extend.ai/2025-04-21/llms.txt
> - v2024-12-23: https://docs.extend.ai/2024-12-23/llms.txt

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.extend.ai/llms.txt
> Use this file to discover all available pages before exploring further.
>
> ## API version
> The current API version is `2026-02-09`, served at the site root (no version prefix in URLs).
> If this page URL contains `/2025-04-21/` or `/2024-12-23/`, you are reading an older API version.
> Prefer the current docs at https://docs.extend.ai/llms.txt unless the user explicitly needs that older version.
> Do not treat older-version pages as the source of truth for new integrations.

# Splitting Configuration

> Configure the Split API with classifications, identifier keys, split rules, the base processor, and parse options.

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](/api-reference/endpoints/split/create-split-run).

> **Prefer a UI?** [Extend Studio](https://dashboard.extend.ai/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`.

| Field           | Type   | Required | Description                                                                               |
| --------------- | ------ | -------- | ----------------------------------------------------------------------------------------- |
| `id`            | string | Yes      | Unique identifier for the classification. Lowercase, underscore-separated is recommended. |
| `type`          | string | Yes      | Type identifier for the classification, returned on each split as `type`.                 |
| `description`   | string | Yes      | A detailed description of the document type. This is your biggest lever on accuracy.      |
| `identifierKey` | string | No       | A natural-language rule for extracting a per-type identifier (see below).                 |

```json
{
  "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.

> **Note**
>
> Supported on `splitting_light` >= 1.3.0 and `splitting_performance` >= 1.5.0. On older versions it is accepted but ignored. It replaces the deprecated `advancedOptions.splitIdentifierRules` field, which set a single global rule.

```json
{
  "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."

```json
{
  "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.

| Processor               | When to use                 |
| ----------------------- | --------------------------- |
| `splitting_performance` | Highest accuracy (default). |
| `splitting_light`       | Faster and cheaper.         |

```json
{
  "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](/model-versioning/splitting/splitting-performance).

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

---

## Advanced options

#### `advancedOptions.splitExcelDocumentsBySheetEnabled`

**Type:** `boolean` (default: `false`)

For Excel documents, split by worksheet.

```json
{
  "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.

> **Note**
>
> Supported on `splitting_light` >= 1.1.0 and `splitting_performance` >= 1.2.0. On older versions it is accepted but ignored.

```json
{
  "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.

> **Note**
>
> This option applies to all `splitting_performance` versions and `splitting_light` >= 1.3.0. Studio only surfaces the **Strict identifiers** toggle (and the `identifierKey` rule it depends on) on `splitting_performance` >= 1.5.0 and `splitting_light` >= 1.3.0.
>
> When omitted, the base version's default applies: enabled on `splitting_performance` >= 1.6.2 and `splitting_light` >= 1.4.1, disabled on earlier versions. Set the field explicitly to override the version default.

```json
{
  "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.

```json
{
  "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](/parsing/configuration) for the full set of options.

```json
{
  "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](/evaluation/processors) — see that page for how saving a configuration lets you version, evaluate, and optimize it.

* [Create a splitter](/api-reference/endpoints/split/create-splitter) — set up a new splitter with your configuration.
* [Update a splitter](/api-reference/endpoints/split/update-splitter) — modify an existing splitter's configuration.
* [Run a splitter](/api-reference/endpoints/split/create-split-run) — execute a splitter, optionally with `splitter.overrideConfig`.