Document Classification

The Document Classification API categorises documents into pre-defined types based on their content. It uses LLMs to intelligently analyse documents and assign them to the most appropriate category from your list.

How It Works

1. You send a document along with a list of categories and their descriptions
2. AISAY analyses the document content
3. It returns the best matching category along with a confidence score

This is useful when you receive a mix of document types (e.g., passports, bank statements, NRICs) and need to sort them automatically before processing.

Available Models

Category Structure

Define your categories as an array of objects, each with a category name and a description that helps the AI understand what the category represents.

[
  {
    "category": "PASSPORT",
    "description": "Official international travel document issued by ICA, containing the holder's photo, name, nationality, and passport number"
  },
  {
    "category": "BANK_STATEMENT",
    "description": "A periodic statement from a financial institution (e.g., DBS, OCBC, UOB) showing account transactions, balances, and account holder details"
  },
  {
    "category": "NRIC",
    "description": "National Registration Identity Card issued by ICA, displaying the holder's name, NRIC number, race, date of birth, and photo"
  },
  {
    "category": "PAYSLIP",
    "description": "A document from an employer showing salary details including gross pay, deductions, CPF contributions, and net pay"
  },
  {
    "category": "UNCLASSIFIED",
    "description": "Any document that does not fit into the defined categories above"
  }
]Copy to clipboardErrorCopied

Tip: Always include an UNCLASSIFIED or OTHER category as a catch-all. This prevents the API from forcing a poor match.

Tips for Better Classification

• Write descriptive descriptions — The more detail you provide, the more accurately the API can distinguish between similar document types
• Use distinctive features — Mention unique visual or textual features that distinguish each category (e.g., “contains a barcode and MOM logo” for a work permit)
• Include an “Other” category — This gives the API an out when a document doesn’t match any defined type
• Test with edge cases — Try documents that are borderline between two categories and refine your descriptions

API Request

import requests
import json
import urllib3

# Disable SSL warnings for dev/internal endpoints
urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)

# 1. Configuration
API_KEY = "YOUR_API_KEY_HERE"
API_URL = "https://api.aisay.tech.gov.sg/v1/classify"
FILE_PATH = "path/to/your/document.pdf"

# 2. Define Categories (Generated by AI)
document_categories = [
    {
        "category": "PASSPORT",
        "description": "Official government-issued identity document for international travel, typically containing a photograph, personal details like name, date of birth, nationality, signature, and an expiry date."
    },
    {
        "category": "BANK_STATEMENT",
        "description": "A periodic summary from a financial institution detailing all transactions (deposits, withdrawals, transfers) in a specific account over a defined period, showing opening and closing balances, and often the account holder's name and address."
    },
    {
        "category": "PAYSLIP",
        "description": "A document issued by an employer to an employee, detailing the employee's gross earnings, itemized deductions (e.g., CPF contributions, income tax), and net pay for a specific pay period."
    },
    {
        "category": "UNCLASSIFIED",
        "description": "Any document submitted as part of a loan application that does not fit into the defined 'PASSPORT', 'BANK_STATEMENT', or 'PAYSLIP' categories."
    }
]

# 3. Prepare Request
headers = {
    "Authorization": f"Bearer {API_KEY}"
}

files = {
    "file": open(FILE_PATH, "rb")
}

data = {
    "document_categories": json.dumps(document_categories),
    "data_classification": "RSN"
}

print(f"Classifying document against {len(document_categories)} categories...")

# 4. Make Request
# verify=False is REQUIRED for dev endpoints using self-signed certs
response = requests.post(API_URL, headers=headers, files=files, data=data, verify=False)

# 5. Process Response
if response.status_code == 200:
    result = response.json()
    print("--------------------------------")
    print(f"📄 DOCUMENT TYPE: {result['document_type']}")
    print("--------------------------------")
    print(f"Full Response: {json.dumps(result, indent=2)}")
else:
    print(f"Error {response.status_code}: {response.text}")
Copy to clipboardErrorCopied

Quick Start with Helper Tool

Visit https://tools.getaisay.com/API_Classification_Helper to generate Python and cURL scripts for your classification use case.

See Also

• API Integration Guide — How to get API keys
• Data Extraction (KIE) — Extract specific fields after classifying
• Pricing — Cost per page