Splitting documents with the Split Agent in n8n

Hello and welcome to the PaperOffice AI Academy. This episode is about the Split Agent in n8n: a batch scan goes in, individual documents come out.

Result first: Batch scan in, documents out

Let’s look at the result first. Our batch scan from the mailroom has seven pages, with a separator sheet in between. The Split Agent recognizes where one document ends and the next one begins. Five documents come back, each with its type, a descriptive name and its pages. Here’s what that looks like in n8n. For a test, I start the workflow in the editor and send the batch scan to the webhook. Now the workflow runs node by node. The split job goes to PaperOffice, and the loop keeps checking until it’s done. After just under forty seconds, everything is finished. The Pieces node holds the result: five entries, one per document. These are the five documents: purchase order, delivery note, invoice, a service bulletin and an inspection report. The service bulletin has two pages, and they stay together. The Split Agent detected the separator sheet on page three and removed it. And each document gets a descriptive name based on our rule. Each piece is its own PDF. Here’s the service bulletin: both pages in one file, named by our rule. The result includes the download link, but it’s only valid for a short time. Here’s a second batch, a harder one: six pages in three languages. An English purchase order, a Spanish delivery note and a Spanish invoice, a credit note, a freight invoice with a coffee stain, and a crooked phone photo of an invoice. The Split Agent separates all six and names them consistently in English. And this is how we build it, in four stages: input, split job, waiting and pieces.

Stage 1 of 4: Input

Stage one is the input: a webhook with header auth that accepts the file via POST. If the file is missing, the workflow immediately responds with a clear error. And what happens without a file? I send a request without an attachment. The workflow takes the short path through the File missing node and responds right away with status 400 and a clear message. No split job is created, so there are no costs either.

Stage 2 of 4: Split job

Stage two sends the batch to the Split Agent, with a single HTTP call to the PaperOffice API. It includes the split template, the Ultra model and a rule for naming the parts: document type, date, sender. In the model field, you choose the scope. Basic detects the boundaries and names the parts. Premium also reads the document type, date and sender. Ultra additionally gives the reasoning for every cut and provides an audit trail. Billing is per page. Two things determine the price: the scope and the processing lane. We chose instant, meaning an immediate start. Without a start guarantee, with no SLA, it costs less. You’ll find the current prices on our website under Pricing.

Stage 3 of 4: Waiting

The job runs in the background. Every six seconds, the loop checks its status. When it’s done, the run continues. If it fails, the run ends with a message.

Stage 4 of 4: Pieces

In stage four, the response becomes a list, one entry per document. If a separator sheet ever comes back as a piece of its own, this node filters it out. Finally, the webhook responds with exactly this list. And what happens to the list next? In the main video on the inbox, this is exactly where the loop takes over: each document goes to the IDP Agent on its own, gets read and is filed in a workspace. That way, the split becomes the start of an entire workflow.

Build it yourself: Credentials and calling from outside

To build this yourself, you need two credentials, both as header auth in n8n. You choose the key for the webhook yourself, with a custom header name. For PaperOffice, you use an API key from your account, under API and developers. It goes into the Authorization header. From outside, you call the workflow with a POST to the webhook URL: the file in the file field, the key in the header. That can be a script, another program or a second workflow. What comes back is the list of documents, ready for the next step. Three tips from practice. First: you don’t need separator sheets; the Split Agent detects the boundaries from the content. Second: you set the naming rule in the naming instruction field, for example date, sender, document type. And third: download the pieces promptly or file them right away, because the links expire after a short time. That was the Split Agent in n8n: a webhook, a call, a loop and a list. In PaperOffice, you can also start it directly from the document list. The main video on the inbox shows how the individual documents continue from there. Until next time in the PaperOffice AI Academy.