How to classify documents
Classify labels a document against the categories you define. Without categories, it suggests a document type. Use it to route or triage documents before processing them.
Quick start
Classify takes the same document input, plus the categories you want to choose between. It labels the document with one type. Without categories, it suggests a document type.
Classify options
config.categories: optional, up to 200 entries. Each requires atype;descriptionis optional. Omit them to let the API read types fromconfig.instructions, or suggest one.config.instructions: your own instruction text, up to 8,000 characters.config.unmatched_behavior:suggest_type(the default) returns asuggested_typewhen no category fits;othersuppresses it.config.label_mode:single(the only value).config.review_policy.min_class_confidence: 0–1, default0.9.
Classify returns a single decision for the document. For an answer per document in a bundle, use Split with categories.
Choose which pages to read
Pick one, not both:
max_pages(top level): read the first N pages. To read every page, send N at least the page count.config.page_ranges: read exactly these pages — a string such as"1-3,5,9-12"or a list such as[{"start": 1, "end": 3}]. 1-based and inclusive.
With neither, the service reads the first 2 pages and the last page, and reads more (up to 16) only when unsure. Sending both returns 422 PAGE_SELECTION_CONFLICT. Quality and verification are managed by the service — do not send quality.
Classify results
When no category matches, the job still completes: you get classification_status: "unknown" and reason_code: "no_matching_type", and, with suggest_type, the document’s own type in suggested_type. Classify always returns one decision for the document; page-by-page answers come from Split with categories.
Results are short by default. Add ?include=details to the results request for the inspected pages and provenance.
Split, then classify
Classify reads the pages you point it at, so a bundle of several documents can look like one. Split first, then classify each child document by its document_ref. To classify one child document, send a JSON body instead of a file:
Classify shares its request behaviours (multiple documents, Idempotency-Key, capabilities) with Split. See Request behaviours.