# Classify documents by type with one API call

> Sort incoming files into your own document types (invoice, W-2, pay stub, statement) with the Reducto Classify API and plain-language criteria.

Canonical: https://reducto.ai/cookbooks/classify-documents-api

Send a document to Reducto Classify with your categories and a few plain-language criteria for each. The response names the matching category and gives a confidence per category and per criterion, so you can route each file to the right extraction schema or to review. No training data needed.

## What you'll build

Synthetic pay stub and W-2 (or your own file)

- List your document types as categories.
- Give each category two or three criteria that describe what it contains.
- Call /classify and read result.category.
- Check response_confidence and route low-confidence files to review.

## Setup

Grab an API key from <a href="https://studio.reducto.ai" rel="noopener noreferrer" target="_blank">studio.reducto.ai</a> -> API Keys -> Create new API key, then set it and install the SDK:

```bash
export REDUCTO_API_KEY="your-api-key-here"
pip install reductoai   # or: npm install reductoai
```

## Step 1: Call `/classify`

The options that matter for this job:

- `classification_schema`: Your document types, each with a list of plain-language criteria.

```python
# pip install reductoai
from pathlib import Path
from reducto import Reducto

client = Reducto()  # reads REDUCTO_API_KEY

upload = client.upload(file=Path("document.pdf"))
result = client.classify.run(
    input=upload.file_id,
    classification_schema=[
        {
            "category": "pay_stub",
            "criteria": [
                "earnings statement for one pay period",
                "lists current and year-to-date earnings and deductions",
            ],
        },
        {
            "category": "w2",
            "criteria": [
                "IRS Form W-2 wage and tax statement",
                "numbered boxes for wages and taxes withheld",
            ],
        },
        {
            "category": "bank_statement",
            "criteria": [
                "account statement with opening and closing balance",
                "list of deposits and withdrawals",
            ],
        },
        {
            "category": "invoice",
            "criteria": [
                "bill from a vendor",
                "invoice number, line items and amount due",
            ],
        },
    ],
)
print(result)
```

```javascript
// npm install reductoai

const client = new Reducto(); // reads REDUCTO_API_KEY

const upload = await client.upload({ file: fs.createReadStream("document.pdf") });
const result = await client.classify.run({
  input: upload.file_id,
  classification_schema: [
    {
      category: "pay_stub",
      criteria: [
        "earnings statement for one pay period",
        "lists current and year-to-date earnings and deductions",
      ],
    },
    {
      category: "w2",
      criteria: [
        "IRS Form W-2 wage and tax statement",
        "numbered boxes for wages and taxes withheld",
      ],
    },
    {
      category: "bank_statement",
      criteria: [
        "account statement with opening and closing balance",
        "list of deposits and withdrawals",
      ],
    },
    {
      category: "invoice",
      criteria: [
        "bill from a vendor",
        "invoice number, line items and amount due",
      ],
    },
  ],
});
console.log(JSON.stringify(result, null, 2));
```

Or with curl:

```bash
# 1. Upload the file (or pass a public URL as "input" and skip this step)
curl -s https://platform.reducto.ai/upload \
  -H "Authorization: Bearer $REDUCTO_API_KEY" \
  -F file=@document.pdf
# => {"file_id": "reducto://..."}

# 2. Run classify
curl -s https://platform.reducto.ai/classify \
  -H "Authorization: Bearer $REDUCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": "reducto://FILE_ID",
  "classification_schema": [{"category": "pay_stub", "criteria": ["earnings statement for one pay period", "lists current and year-to-date earnings and deductions"]}, {"category": "w2", "criteria": ["IRS Form W-2 wage and tax statement", "numbered boxes for wages and taxes withheld"]}, {"category": "bank_statement", "criteria": ["account statement with opening and closing balance", "list of deposits and withdrawals"]}, {"category": "invoice", "criteria": ["bill from a vendor", "invoice number, line items and amount due"]}]
}'
```

## Step 2: Read the result

On the sample (a synthetic pay stub and W-2), the job-specific part of the response:

```json
{
  "category": "pay_stub"
}
```

The category is one of the labels you defined, so the next step can route the file to the right schema.

[Full response format ->](https://docs.reducto.ai/classify/response-format)

## When to use something else

- **Classify**: when each file is one document and you need its type.
- **Split**: when one file holds several documents.
- **Extract**: when you already know the type and need its fields.

## Where this goes next

- [Reducto Classify](/classify)
- [Split a PDF by document type](/cookbooks/split-pdf-by-document-type)
- [W-2, 1099 and pay stub extraction](/cookbooks/w2-1099-paystub-extraction)
