# 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](/split) found before extracting from them.

**Before you start.** You need an API key from the [quickstart](/quickstart)
and a document that has already been [parsed](/parsing) — 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](/errors) 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](/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

```bash
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

```bash
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](/workflows).

## Where to next

- [Split](/split) — separate a combined PDF into records before labelling
  them.
- [Extraction](/extraction) — pull typed fields out of the documents you just
  labelled.
- [API reference](/api/document-classification) — every request body and
  response field.