> ## 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.

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.

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.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`.