Articles in this section

Classify documents and route them by type

Michelle Welch
Updated

Overview

You classify documents in integrator.io with an AI agent that reads each document and returns its type from a list you define. A branch then routes each type to its own extraction agent and destination: invoices to accounts payable, purchase orders to order entry, remittance advice to cash application, and anything unrecognized to a person.

Use classification when one folder, mailbox, or trading partner sends several kinds of documents. A classifier with a short, fixed list of types is fast and inexpensive, and an extraction agent built for one document type returns more accurate data than one agent that handles every type.

Prerequisites:

Create a classifier agent

A classifier agent returns a document type, and optionally how certain it is and why. Classification is a simpler task than extraction, so a smaller, faster model is often enough. Compare models on your samples in the agent's preview.

  1. Add an AI agent after the step that brings in the documents, and map each file to the agent's files input.
  2. Set the output type to JSON, and define a schema with a document_type field limited to your types.
  3. In Instructions, describe each type by the features that set it apart.

Example instructions:

Classify the attached document. Return exactly one document_type.

  • invoice: a request for payment from a vendor, with an invoice number and an amount due.
  • purchase_order: an order from a customer or partner to buy goods, with a PO number and ordered lines.
  • remittance_advice: a notice from a customer listing payments applied to invoices.
  • bill_of_lading: a shipping document from a carrier, with shipper, consignee, and freight details.
  • other: anything else, including documents that combine types.

Set confidence to low when the document could reasonably be more than one type or is hard to read. Explain your choice in one sentence in reason.

Example schema:

{
  "type": "object",
  "properties": {
    "document_type": {
      "type": "string",
      "enum": ["invoice", "purchase_order", "remittance_advice", "bill_of_lading", "other"],
      "description": "The single best type for the document"
    },
    "confidence": {
      "type": "string",
      "enum": ["high", "medium", "low"],
      "description": "How clearly the document matches the chosen type"
    },
    "reason": { "type": "string", "description": "One sentence explaining the classification" }
  },
  "required": ["document_type", "confidence", "reason"],
  "additionalProperties": false
}

The confidence value is the model's own assessment of the document, not a calibrated probability. Use it to route borderline documents to review, together with the checks later in the flow.

Route each document type

  1. Add a response mapping on the classifier to bring _json.document_type, _json.confidence, and _json.reason into the record.
  2. Add a branch after the classifier. With first matching branch, the first condition that matches decides the route.
  3. Put the review condition first: confidence is low or document_type is other. Route it to your review path, such as error management with a message that includes the reason. See Validate extracted data and route exceptions for review.
  4. Add one branch per document type, for example document_type is invoice.
  5. On each branch, add an extraction agent with a schema for that type, followed by the validation and destination steps for that type. See Extract data from documents.

The same file reference travels with the record, so each extraction agent reads the original document. See Apply branching to your flow.

Classify and extract in one agent

For two or three closely related types that share most fields — for example, invoices and credit memos — one agent can return document_type along with the fields for both. Add a branch on document_type after the agent. When the types don't share fields, separate agents with focused schemas are easier to maintain and more accurate.

Start from a Marketplace template

The AI Powered Document Processing template classifies files dropped into Celigo Storage into 11 document types and routes each to its own extraction agent, and the AI EDI Document Classify-and-Route Agent template identifies the EDI and non-EDI files trading partners drop. In Marketplace, filter By type and select AI Agents. See Intelligent document processing overview.

Tips

  • Keep an other type — A classifier that must choose from known types forces unfamiliar documents into the wrong one. Route other to review, and watch its volume to find types worth adding.
  • Keep type values stable — Branch conditions depend on the exact values in the enum. Add types; don't rename them.
  • Describe differences, not names alone — "A remittance advice lists payments applied to invoices" helps more than the word "remittance."
  • Classify without AI when the format tells you — When a file's name, sender, folder, or structure already identifies it, route it with a branch condition and save the agent for files that need it.

Related articles