Per-File Split Policies

When you submit several files in one transaction, the Split step decides how their pages become documents. By default that decision is driven entirely by the project's split mode. If the project uses intelligent splitting, the model looks at all pages as one continuous stream, so a document may start in one file and continue in the next.

That is the right behavior when files are arbitrary scans. It is the wrong behavior when you already know how a file was produced. Two common examples:

• An email body rendered to PDF is always exactly one document. It should never be merged with the attachments that follow it.
• A PDF attachment may contain several documents, but a document never continues from one attachment into the next.

A split policy lets you state such a guarantee per file at upload time. The Split step then treats it as a hard constraint.

The three policies

split_policy	Your promise about the file	What Split does
inherit (default)	None	The project's split mode governs. Pages may merge with neighboring files if the mode allows it.
single_document	The file is exactly one complete document	The file becomes one document. No boundary analysis runs on it.
self_contained	The file contains one or more complete documents	Intelligent boundary detection runs inside this file only. Documents never cross the file's borders.

Policies always win over the project split mode, but only for the files they are set on. Files without a policy behave exactly as before.

One-step API

Set split_policy on each entry in source_files:

curl -X POST "https://app.docaifabric.com/tenants/{tenant_id}/projects/{project_id}/transactions/process" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "source_files": [
      {
        "filename": "email_body.pdf",
        "base64_data": "JVBERi0xLjQK...",
        "split_policy": "single_document"
      },
      {
        "filename": "attachment_1.pdf",
        "base64_data": "JVBERi0xLjQK...",
        "split_policy": "self_contained"
      },
      {
        "filename": "attachment_2.pdf",
        "base64_data": "JVBERi0xLjQK...",
        "split_policy": "self_contained"
      }
    ]
  }'

In this example the body PDF is guaranteed to come out as one document, and each attachment is analyzed on its own. If an attachment holds three invoices, it produces three documents, but an invoice can never span two attachments.

Multi-step API

On the multipart upload endpoint, send one split_policies form field per file. Values are matched to files by position, the same way upload_tokens works:

curl -X POST "https://app.docaifabric.com/transactions/{transaction_id}/source-files" \
  -H "X-API-Key: your-api-key" \
  -F "files=@email_body.pdf" \
  -F "split_policies=single_document" \
  -F "files=@attachment_1.pdf" \
  -F "split_policies=self_contained"

An invalid value returns 400 with the list of allowed values. If you upload files one at a time, send the matching single split_policies value with each request.

Behavior details

• A pinned file breaks the page stream. If file B between files A and C carries single_document or self_contained, the pages of A and C are analyzed separately and can never merge into one document, even in intelligent mode.
• Predefined documents skip split review. A document produced by single_document (or by a one-page file) gets split confidence 1.0 and is never flagged for split review.
• Policies survive re-runs. They are stored on the transaction, so re-running the workflow from the Split step applies the same constraints.
• Disabled split ignores policies. If the project's Split step is disabled, every file becomes one document regardless of policies.
• self_contained works with any project mode. Even if the project uses a deterministic mode such as one document per source file, a file marked self_contained is still analyzed with the intelligent splitter, using the project's split settings (classes, guidelines, model).

Project-wide alternative

If every file in your workload is self-contained, you do not need per-file policies. Set the project's split mode to Intelligent LLM Splitting Within Files (intelligent_llm_per_source) instead. It behaves as if every uploaded file carried self_contained. See Split activity.

Use per-file policies when files in the same transaction need different treatment, as in the email example above.

Email import connector

The email import connector applies this automatically: the rendered email body PDF is uploaded with split_policy: "single_document", so it never merges with attachments. Attachments are uploaded with inherit and follow the project's split mode.

Choosing a policy

Your situation	Recommendation
Files are arbitrary scans, one document may span files (e.g. a scanner that emits one file per page)	inherit with project mode Intelligent LLM Splitting
Every file is a complete bundle, boundaries inside files are unknown	Project mode Intelligent LLM Splitting Within Files, no per-file policies needed
Mixed: some files are known single documents, others need analysis	Per-file policies, as in the email example
Every file is exactly one document	Project mode One Document Per Source File, no policies needed