Skip to navigation

How to classify documents

View as Markdown

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.

You provideA document (+ categories, optional)
EndpointPOST /doc-ai/v1/job/classify
OutputA document type, with reasoning and a review flag
InputPDF, PNG, JPEG, TIFF; up to 500 pages and 512 MB per document

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.

import os, time
from sarvamai import SarvamAI
from sarvamai.core.api_error import ApiError
client = SarvamAI(api_subscription_key=os.environ["SARVAM_API_KEY"])
try:
# Create and submit a classify job in one call
with open("./sample-document.pdf", "rb") as f:
job = client.doc_ai.classify(
file=[("sample-document.pdf", f, "application/pdf")],
request={
"max_pages": 2,
"config": {
"categories": [
{"type": "Invoice", "description": "A supplier bill with totals and payment details."},
{"type": "Receipt", "description": "Proof of a completed payment."},
],
},
},
)
print("job created:", job.job_id, "| status:", job.status)
# Poll until the job reaches a terminal state
TERMINAL = {"completed", "partially_completed", "failed", "rejected"}
while True:
st = client.doc_ai.get_status(job_id=job.job_id)
print(f"status={st.status} phase={st.phase}")
if st.status.lower() in TERMINAL:
break
time.sleep(5)
# Fetch the decision
if st.status.lower() in ("completed", "partially_completed"):
results = client.doc_ai.get_results(job_id=job.job_id)
d = results.result
print(d.type, d.classification_status, "review:", d.review_required)
except FileNotFoundError:
print("Document file not found: ./sample-document.pdf")
except ApiError as e:
print(f"API error {e.status_code}: {e.body}")

Classify options

  • config.categories: optional, up to 200 entries. Each requires a type; description is optional. Omit them to let the API read types from config.instructions, or suggest one.
  • config.instructions: your own instruction text, up to 8,000 characters.
  • config.unmatched_behavior: suggest_type (the default) returns a suggested_type when no category fits; other suppresses it.
  • config.label_mode: single (the only value).
  • config.review_policy.min_class_confidence: 0–1, default 0.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

{
"job_id": "01a17998-120b-73dc-ad42-5cd66e0fe0ff",
"type": "classify",
"status": "completed",
"result": {
"type": "Invoice",
"classification_status": "matched",
"confidence": 1,
"reasoning": "The document is explicitly titled 'INVOICE #2001' and contains a total amount due.",
"review_required": false,
"review_reasons": [],
"suggested_type": null
},
"usage": {"pages_processed": 2, "pages_source": 2}
}
FieldMeaning
typeThe matching category. null when the status is unknown or mixed; other when nothing matched and unmatched_behavior is other
classification_statusmatched (a category fits), unknown (none fits), or mixed (the file holds several documents)
reason_codeOn unknown: no_matching_type, or insufficient_evidence when the pages were not enough to tell
confidenceA token-based score from 0 to 1, or null. It is not a measured probability of being correct
review_requiredWhether a person should check the answer. Low or missing confidence and unresolved answers require review
review_reasonsFor example NO_MATCHING_TYPE, MODEL_SCORE_UNAVAILABLE, or MULTIPLE_DOCUMENTS_DETECTED
suggested_typeA type you did not supply, with its name and supporting evidence. null when there is nothing to suggest

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:

curl -X POST https://api.sarvam.ai/doc-ai/v1/job/classify \
-H "api-subscription-key: $SARVAM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input": {"document_ref": "doc_..."}, "config": {"categories": [{"type": "Invoice", "description": "A supplier bill."}]}}'

Classify shares its request behaviours (multiple documents, Idempotency-Key, capabilities) with Split. See Request behaviours.

Next steps