Classify

Classification assigns a type label — with a confidence score and evidence — to a document and to each of its pages. Use it to route intake, or to label the records a split found before extracting from them.

Before you start. You need an API key from the quickstart and a document that has already been parsed — an unparsed file returns 409 file_must_be_parsed. Classification needs the extract.run permission and viewer access to the file. Failures carry a stable code; the full list is on the error codes page.

Both classify endpoints are synchronous. They run the model in the request and return the result body directly — there is no operation to poll, even though a classify_run row is written for audit. That is the opposite of split, which queues. The model call is slow — minutes on a large document — so set a generous client timeout and expect any proxy in front of the API to be the binding constraint.

Suggest classes

Code
curl -s -X POST "$DOCAI_API/v1/classify/classes/suggest" \
  -H "x-api-key: $DOCAI_API_KEY" -H "content-type: application/json" \
  -d '{"file_id":"'"$FILE_ID"'","guidelines":"Separate correspondence from filings"}'

Returns { operation_id, classes, warnings, modelId, credit }. Each class has id, name, description and examples. Edit them and pass them to the run.

Classify

Code
curl -s -X POST "$DOCAI_API/v1/classify/runs" \
  -H "x-api-key: $DOCAI_API_KEY" -H "content-type: application/json" \
  -d '{"file_id":"'"$FILE_ID"'","classes":[{"name":"Invoice"},{"name":"Correspondence"}]}'

classes may be replaced by labels, a plain array of names.

The run returns { operation_id, classes, classifications, pageClassifications, quality, warnings, modelId, credit }.

• classifications — one document-scope entry first, then every page. Each has id, scope, classId, label, topic, confidence, pageNumber, segmentId, segmentIds and evidence.
• pageClassifications — the same list filtered to scope: "page". Every page is present: a page the model did not cover is filled in at confidence 0.35 with an evidence string saying so.
• quality — pageCount, classifiedPages, coverage, lowConfidencePages, missingPages, and status of ready or review. Anything below 0.6 confidence pushes the status to review.

Classifications are persisted, so they remain available for filtering after the response is gone.

Cost and model controls

Classes suggest and a classify run each debit exactly one credit, debited before the model runs. Synchronous workflows do not refund on failure — retrying with the same idempotency_key re-runs the model without a second charge, and a completed run replays its stored output for free. The shared request fields — model_id, reasoning_level, idempotency_key — and the full credit semantics are on document workflows.

Where to next

• Split — separate a combined PDF into records before labelling them.
• Extraction — pull typed fields out of the documents you just labelled.
• API reference — every request body and response field.