Skip to main content

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).

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​

FieldTypeRequiredDescription
namestringYesA descriptive name for this classifier (e.g. "Document Type Router").
configsobjectYesClassification settings. See below.

configs Object​

FieldTypeRequiredDescription
classesarrayYesList of category objects. Each must have label and description. Minimum 2.
classifier_typestringNo"document" (default) classifies the whole document as one unit.
query_modelstringNoAI model to use. Options: "gpt-4o-mini" (default), "gpt-4o".
page_rangestringNoPages 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.

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",
  "configs": {
    "classifier_type": "document",
    "classes": [
      { "label": "invoice", "description": "A document requesting payment for goods or services rendered" },
      { "label": "purchase_order", "description": "A buyer-issued document authorizing a purchase from a supplier" },
      { "label": "contract", "description": "A legally binding agreement between two or more parties" },
      { "label": "other", "description": "Any document that does not fit the above categories" }
    ],
    "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",
    "configs": {
        "classifier_type": "document",
        "classes": [
            { "label": "invoice", "description": "A document requesting payment for goods or services rendered" },
            { "label": "purchase_order", "description": "A buyer-issued document authorizing a purchase from a supplier" },
            { "label": "contract", "description": "A legally binding agreement between two or more parties" },
            { "label": "other", "description": "Any document that does not fit the above categories" }
        ],
        "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" },
            { "label": "purchase_order", "description": "A buyer-issued document authorizing a purchase from a supplier" },
            { "label": "contract", "description": "A legally binding agreement between two or more parties" },
            { "label": "other", "description": "Any document that does not fit the above categories" }
        ],
        "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.
  • created_at / updated_at: UTC timestamps.

Next Steps​