Classify

Classify a document into one of the provided categories.

This endpoint analyzes a document and classifies it into exactly one of the user-defined categories, returning the classification with chain-of-thought reasoning explaining the decision.

Example use cases:

• Classifying invoices vs receipts vs contracts
• Identifying document types in a processing pipeline
• Routing documents to appropriate handlers based on content
• Pre-filtering documents before extraction

POST /v1/documents/classify

python

from retab import Retab

client = Retab()

# Classify a document into one of the provided categories
# Use first_n_pages to only analyze the first 3 pages (useful for large documents)
result = client.documents.classify(
    document="invoice.pdf",
    model="retab-small",
    categories=[
        {"name": "invoice", "description": "Invoice documents with billing information"},
        {"name": "receipt", "description": "Receipt documents for payments"},
        {"name": "contract", "description": "Legal contract documents"},
    ],
    first_n_pages=3,  # Optional: only use first 3 pages for classification
    context="Processing batch from Q4 2024 vendor submissions"  # Optional: additional context
)

# Access classification result
print(f"Classification: {result.result.classification}")
print(f"Reasoning: {result.result.reasoning}")

# Example output:
# Classification: invoice
# Reasoning: The document contains billing details including line items, 
# unit prices, quantities, and a total amount due. It has a header with 
# "INVOICE" and includes payment terms and a due date.

200

{
  "result": {
    "reasoning": "The document contains billing details including line items, unit prices, quantities, and a total amount due. It has a header with 'INVOICE' prominently displayed and includes standard invoice elements such as invoice number, date, payment terms, and a due date. The format and content are consistent with typical invoice documents.",
    "classification": "invoice"
  }
}

python

from retab import Retab

client = Retab()

# Classify a document into one of the provided categories
# Use first_n_pages to only analyze the first 3 pages (useful for large documents)
result = client.documents.classify(
    document="invoice.pdf",
    model="retab-small",
    categories=[
        {"name": "invoice", "description": "Invoice documents with billing information"},
        {"name": "receipt", "description": "Receipt documents for payments"},
        {"name": "contract", "description": "Legal contract documents"},
    ],
    first_n_pages=3,  # Optional: only use first 3 pages for classification
    context="Processing batch from Q4 2024 vendor submissions"  # Optional: additional context
)

# Access classification result
print(f"Classification: {result.result.classification}")
print(f"Reasoning: {result.result.reasoning}")

# Example output:
# Classification: invoice
# Reasoning: The document contains billing details including line items, 
# unit prices, quantities, and a total amount due. It has a header with 
# "INVOICE" and includes payment terms and a due date.

200

{
  "result": {
    "reasoning": "The document contains billing details including line items, unit prices, quantities, and a total amount due. It has a header with 'INVOICE' prominently displayed and includes standard invoice elements such as invoice number, date, payment terms, and a due date. The format and content are consistent with typical invoice documents.",
    "classification": "invoice"
  }
}

Authorizations

Api-Key · string · header · required

Query Parameters

access_token · string | null

Body

application/json

document · MIMEData · object · required

The document to classify

Show child attributes

categories · Category · object[] · required

The categories to classify the document into

Show child attributes

model · string · default: retab-small

The model to use for classification

first_n_pages · integer | null

Only use the first N pages of the document for classification. Useful for large documents where classification can be determined from early pages.

context · string | null

Additional context for classification (e.g., iteration context from a loop)

Response

200

application/json

Successful Response

result · ClassifyResult · object · required

The classification result with reasoning

Show child attributes