Document classifiers

SaaS ·

Available on SaaS with FlowX.AI . This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

A Document Classifier is a trained machine-learning model that sorts document pages into categories you define, such as INVOICE, NATIONAL_ID, or BANK_STATEMENT, so a workflow can route each page to the right handling. Classification is deterministic: the same page always gets the same result, and no large language model runs at inference time. Document Classifiers live in your project under Integrations → Document Classifiers, alongside Data Sources, Workflows, and Proxy Connections.

When to use a Document Classifier

FlowX offers two ways to classify documents. Pick based on how well-defined your document types are and how much labeled data you have:

Approach	Best for
Document Classifier (this page)	Narrow, well-defined document types at scale. Deterministic results, low latency, low cost per page. Needs labeled example pages to train.
LLM-based classification with a Custom Agent	Standing something up fast without training data, or open-ended document types. Results vary between runs and cost more per page.

Two other features have similar names but do different things: Document Intelligence ingests documents into a knowledge base for AI retrieval, and the Extract Data from File workflow node extracts field values from a document. A Document Classifier only answers one question per page: which category is this?

Create a Document Classifier

Open Document Classifiers

In your project, go to Integrations → Document Classifiers and click +.

Name the classifier

Enter a Name and an optional Description.

Choose how the model gets trained

Leave Use preexisting model bundle toggled OFF to create an empty classifier and train it in FlowX (the usual path). Toggle it ON to import a model bundle exported from another FlowX environment. See Import a pre-trained bundle.

The classifier detail page has three tabs (Classes, Data, and Trained Models) that mirror the three parts of a classifier: a label taxonomy, a labeled page corpus, and trained model versions.

Define classes

Classes are the categories the model sorts pages into. Open the Classes tab and click New class.

string

required

Must be UPPER_SNAKE_CASE (letters, digits, underscores, starting with a letter, such as NATIONAL_ID) and unique within the classifier.

string

required

Describe what differentiates this class from the others. The description guides automatic pre-labeling when you upload unlabeled documents.

list

Snippets of text likely to appear verbatim in a document of this class.

list

Snippets that look like this class but are not. They help the model separate near-misses.

Every classifier ships with a locked UNKNOWN class as the default catch-all. Pages that don’t belong to any of your classes get labeled UNKNOWN instead of landing in a wrong category.

Define at least two classes besides UNKNOWN, and make them mutually exclusive. If two classes overlap heavily, merge them and let a downstream step tell them apart.

Build the corpus

The unit of classification is a page, not a file. The Data tab is where labeled pages accumulate into the training corpus. There are two ways to add pages:

Upload unlabeled batch: drop ZIP, PDF, or Word files. Source files can be up to 20 MB each. The pages are pre-labeled automatically and queued for your review; each page needs review before it joins the corpus.
Upload sorted by class: drop files that are already sorted per class; the pages join the corpus directly, without review.

Added pages join the corpus with an automatic 80% train / 20% test split, assigned per class when the page enters and never reshuffled, so test results stay comparable between training runs. Pages labeled UNKNOWN go entirely to the test pool. The corpus table shows every page with its class, split, and upload batch. You can remove pages, but not relabel them in place.

Train a model

In the Data tab, select the training pages to use and click Train model. Training requires at least 10 training pages for every class; the locked UNKNOWN class is exempt. A warning appears when the corpus is heavily imbalanced: when one class has far more pages than another, the model tends to over-predict the bigger one. Training runs asynchronously. Each successful run produces an immutable model version in the Trained Models tab, with its accuracy metrics, per-class results, and a confusion matrix. You can compare any two versions to see what changed between training runs. The main version is the one workflows use. The first trained version becomes main automatically; promote a different version when it performs better.

Training and promotion work on the draft (WIP) version of your project. Committing a project version freezes the classifier’s corpus and training for that version. Editing a committed classifier continues on a new draft.

What travels between environments

When you export or build a project, the classifier’s class taxonomy travels with it as part of the versioned configuration. The corpus and trained models do not travel: the target environment receives the classes and trains against its own data.

Import a pre-trained bundle

If you already have a model trained in another FlowX environment, toggle Use preexisting model bundle ON when creating the classifier and upload the exported bundle: a ZIP with the model metadata and binary. FlowX validates the bundle on upload and adds it as an uploaded candidate version:

It must define at least two classes, named in UPPER_SNAKE_CASE, without duplicates.
Its training metrics must be present and consistent with the declared class set.
FlowX rejects a bundle that fails validation; nothing is created. A bundle that uploads but fails processing leaves the classifier in a Failed state with a Retry option.

Bundles are produced by FlowX. Export them from an environment where the model was trained: hand-assembled bundles fail validation or produce meaningless predictions, because the model’s features are tied to how it was trained.

Classify pages in a workflow

Consume the trained model with the Document Classification node from the workflow node palette. The node is a pure classifier: it labels pages and writes the result. Routing happens in a downstream condition node.

Field	Description	Default
Document Classifier	The classifier whose main model version runs. A read-only Classes hint lists its labels so you can build the downstream condition.	N/A
File Content	An expression that resolves to an array of extracted page texts, one entry per page, such as `${extractedPages}`.	N/A
Confidence Threshold	Predictions below this probability get flagged `low_confidence`.	`0.7`
Response Key	The key the node writes the result JSON under.	`responseKey`
Timeout	Inference call timeout, in milliseconds.	`10000`

The node classifies text, not files. Extract page text upstream, for example with the Extract Data from File node or your document processing flow, and pass the array of page texts to File Content.

Output

The node classifies each page independently and writes one result object:

{
  "pages": [
    {
      "page": 1,
      "predictedLabel": "NATIONAL_ID",
      "predictedProbability": 0.92,
      "low_confidence": false,
      "classes": [
        { "label": "NATIONAL_ID", "probability": 0.92 },
        { "label": "PASSPORT", "probability": 0.05 }
      ],
      "error": null
    }
  ],
  "confidenceThreshold": 0.7,
  "error": null
}

predictedLabel is the highest-probability class; classes lists all class probabilities in descending order.
low_confidence is true when predictedProbability is below the configured threshold. A low-confidence prediction is still a successful result. Use the condition node to route those pages to human review instead of treating them as failures.
A single page failing to classify populates that page’s error and the node still succeeds; the other pages classify normally.
Whole-node failures set the top-level error and route to the node’s error output. The error codes:

Code	Meaning
`MODEL_NOT_FOUND`	The selected classifier or its main model version doesn’t exist.
`MODEL_NOT_READY`	The classifier has no trained, ready model version yet.
`NO_DOCUMENT_TEXT`	The File Content expression resolved to nothing.
`EMPTY_INPUT`	The input resolved to an empty page list.
`INVALID_TIMEOUT`	The configured timeout value isn’t usable.
`INFERENCE_UNAVAILABLE`	The classification service is unreachable. Retryable.

Route by label

Add a Condition node after the Document Classification node and branch on the result: typically iterating pages and switching on predictedLabel, with a separate branch for low_confidence pages.

Integration Designer

Build workflows that combine classifiers with REST calls, data operations, and AI nodes

Custom Agent node

LLM-based alternative for classification without training data

Getting Started

Concepts

FlowX.AI Designer

Building projects

Building blocks

Platform deep dive

Resources

API reference

Document classifiers

When to use a Document Classifier

Create a Document Classifier

Define classes

Build the corpus

Train a model

What travels between environments

Import a pre-trained bundle

Classify pages in a workflow

Output

Route by label

Integration Designer

Custom Agent node

​When to use a Document Classifier

​Create a Document Classifier

​Define classes

​Build the corpus

​Train a model

​What travels between environments

​Import a pre-trained bundle

​Classify pages in a workflow

​Output

​Route by label

​Related resources

Integration Designer

Custom Agent node

When to use a Document Classifier

Create a Document Classifier

Define classes

Build the corpus

Train a model

What travels between environments

Import a pre-trained bundle

Classify pages in a workflow

Output

Route by label

Related resources