Create Classifier

A Classifier is a reusable set of categories you define once and apply to many documents. Once created, you can run it against any document using Run Classification — no need to resend your label definitions with each request.

Classifiers are best suited for automation pipelines where the same label set is applied to every incoming document (e.g. routing all inbound emails to the correct Workflow by document type).

A Classifier can also map each label directly to an extraction template, so a single document can be classified and extracted in one call. See Classify + Extract in one call.

API Endpoint

POST https://api.documentpro.ai/v1/classifiers

Headers

• x-api-key (required): Your API key for authentication.
• Content-Type: application/json

Request Body

All fields below are sent flat in the request body (not nested under a configs object). name and classes are required; everything else is optional.

Field	Type	Required	Description
name	string	Yes	A descriptive name for this classifier (e.g. "Document Type Router").
classes	array	Yes	List of category objects. Each must have label and description, and may optionally include a template_id. Minimum 2.
default_template_id	string	No	Fallback extraction template used when the winning label has no template_id mapped, or its confidence is below min_confidence. Used by Classify + Extract.
min_confidence	number (0.0–1.0)	No	If the winning label's confidence is below this threshold, routing falls back to default_template_id. Only relevant when using this classifier with classifier_id on an extract.
classifier_type	string	No	"document" (default) classifies the whole document as one unit.
query_model	string	No	AI model to use. Options: "gpt-4o-mini" (default), "gpt-4o". Must be a supported (non-fine-tuned) model — invalid values return 400.
use_ocr	boolean	No	Defaults to true.
page_range	string	No	Pages to use for classification (e.g. "1-2"). Defaults to all pages.

Each item in classes must have:

• label (string): The category name returned when the document matches (e.g. "invoice").
• description (string): Plain-English description to help the AI distinguish this category.
• template_id (string, optional): The extraction template to run when a document is classified as this label. Only used when this classifier is passed as classifier_id to an extract — see Classify + Extract in one call.

Example Implementation

Using cURL

curl --location 'https://api.documentpro.ai/v1/classifiers' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "name": "Document Type Router",
  "classifier_type": "document",
  "classes": [
    { "label": "invoice", "description": "A document requesting payment for goods or services rendered", "template_id": "tmpl_invoice" },
    { "label": "purchase_order", "description": "A buyer-issued document authorizing a purchase from a supplier", "template_id": "tmpl_po" },
    { "label": "contract", "description": "A legally binding agreement between two or more parties" },
    { "label": "other", "description": "Any document that does not fit the above categories" }
  ],
  "default_template_id": "tmpl_generic",
  "min_confidence": 0.6,
  "query_model": "gpt-4o-mini",
  "page_range": "1-2"
}'

Using Python

import requests
import json

url = "https://api.documentpro.ai/v1/classifiers"

headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

payload = {
    "name": "Document Type Router",
    "classifier_type": "document",
    "classes": [
        { "label": "invoice", "description": "A document requesting payment for goods or services rendered", "template_id": "tmpl_invoice" },
        { "label": "purchase_order", "description": "A buyer-issued document authorizing a purchase from a supplier", "template_id": "tmpl_po" },
        { "label": "contract", "description": "A legally binding agreement between two or more parties" },
        { "label": "other", "description": "Any document that does not fit the above categories" }
    ],
    "default_template_id": "tmpl_generic",
    "min_confidence": 0.6,
    "query_model": "gpt-4o-mini",
    "page_range": "1-2"
}

response = requests.post(url, headers=headers, data=json.dumps(payload))

if response.status_code == 200:
    result = response.json()
    print(f"Classifier created. ID: {result['classifier_id']}")
else:
    print('Failed to create classifier')
    print(response.text)

Response

Successful Response (Status Code: 200)

{
    "classifier_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "Document Type Router",
    "user_id": "4449b25a-9bba-4de4-be67-c06233d2f305",
    "configs": {
        "classifier_type": "document",
        "classes": [
            { "label": "invoice", "description": "A document requesting payment for goods or services rendered", "template_id": "tmpl_invoice" },
            { "label": "purchase_order", "description": "A buyer-issued document authorizing a purchase from a supplier", "template_id": "tmpl_po" },
            { "label": "contract", "description": "A legally binding agreement between two or more parties" },
            { "label": "other", "description": "Any document that does not fit the above categories" }
        ],
        "default_template_id": "tmpl_generic",
        "min_confidence": 0.6,
        "query_model": "gpt-4o-mini",
        "page_range": "1-2",
        "use_ocr": true
    },
    "created_at": "2024-07-25T14:16:44.540197",
    "updated_at": "2024-07-25T14:16:44.540223"
}

Error Response (Status Codes: 400, 403, 500)

{
    "success": false,
    "error": "error_code",
    "message": "descriptive error message"
}

Response Fields Explained

• classifier_id: The unique ID for this classifier. Use it to run classifications, update, or delete this classifier.
• name: The name you provided.
• configs: The saved classification settings, including your full classes list. Note that although the request body is flat, the response always nests these settings under configs.
• created_at / updated_at: UTC timestamps.

Validation

An invalid query_model returns 400. A min_confidence outside the 0.0–1.0 range returns 400.

Next Steps

• Run Classification using the classifier_id to classify documents.
• List your Classifiers to see all classifiers in your account.
• Update a Classifier to modify the label set or settings.