Skip to main content
Classify reads the first pages of a document and tells you which of your categories it belongs to. Use it when one intake receives several kinds of document, and each kind needs its own parse, extraction or pipeline. If you already know the kind, skip it.

Classify a document

Classify reads the document itself, not a parse, so send file or file_url with your categories. This request sorts one scanned file into one of three categories and waits for the answer:
For the call to return at once, send async: true and poll the job: see Jobs and results. Classify reads PDFs, images, TIFFs, Word and PowerPoint files, HTML pages and Excel workbooks: see Files and limits.

Write your categories

config.classifications lists at least one category. Each has a name, which comes back as the answer and can appear only once, and an optional description of what belongs in it. Add a description when two names could be confused. Classify always picks the best match, even when no category fits well, so add a catch-all category such as other for unexpected documents.

Choose pages

By default, Classify reads the first 5 pages, or every page of a shorter document. For other pages, send config.page_range, such as "1-2" or "3, 7-9". A range past the last page is refused with a 400 before the job starts, except in a Word, PowerPoint or HTML document. That document is first turned into pages, then read like a PDF, so there the job fails instead. In an Excel workbook, each sheet is a page, hidden sheets included. Classify reads the text of the selected sheets, up to the first 120,000 characters, rather than an image of them.

Read the result

GET /classify/{classify_id}/result (client.classify.get_result) returns the answer:
classification is exactly one of the names you sent. confidence is always null for now. usage.request.pages_processed counts the pages Classify read.

Route each kind

Classify returns only a name. To act on it, send the same document with the config_id of a saved config for that kind. This example parses invoices and bank statements with their own parse configs and leaves others for review:
To run several steps for each kind, map each name to a saved pipeline config and start a pipeline instead. Classify can’t be a step in a pipeline, so run it first.

Pricing

Classify costs 0.5 credits per page it reads, so at most 2.5 credits per document with the default of 5 pages (Pricing). Each request classifies one document.

Next steps

Saved configs

Save a config for each kind of document.

Classify API reference

Every option, field and limit.