API Integration Guide

This guide walks developers through getting started with the AISAY APIs — from requesting API keys to making your first call.

Prerequisites

• A .gov.sg or .edu.sg email address
• Basic knowledge of REST APIs (Python or cURL)
• A development environment

Step 1: Request API Keys

Staging Keys (Free, for Testing)

Visit https://go.gov.sg/aisaykey to request a free staging API key.

Staging keys are for experimentation and come with usage and throughput limits. They are a good way to test the APIs before committing to production use.

Production Keys

To get production API keys:

1. Express your interest — Submit a request via the form at https://go.gov.sg/aisaykey
2. Evaluation and approval — The AISAY product manager will evaluate your request. Upon approval, you will receive the API credentials required to access AISAY services
3. API documentation — Refer to the API Specifications for details on endpoints, payloads, and usage

Step 2: Choose Your API

AISAY provides three APIs:

Recommendation: Over 90% of use cases are best served by the KIE API. It handles extraction, analysis, and verification. Start with KIE unless you have a specific need for classification or full-text OCR.

Step 3: Choose Your Model

Each API offers two model options:

Try both on your use case to see which performs better.

Step 4: Make Your First API Call

KIE (Extraction) — Python

import requests
import base64
import json

# 1. Encode your file
with open("payslip.pdf", "rb") as f:
    file_base64 = base64.b64encode(f.read()).decode("utf-8")

# 2. Define what you want to extract
vlm_prompt = {
    "type": "object",
    "properties": {
        "employee_name": {
            "type": "string",
            "description": "The full name of the employee as shown on the payslip"
        },
        "net_pay": {
            "type": "string",
            "description": "The final net pay amount. This could be called Net Pay, Final Pay, Total Amount, or Total Salary. Example: $3,860.00"
        }
    },
    "required": ["employee_name", "net_pay"],
    "additionalProperties": False
}

# 3. Call the API
response = requests.post(
    "https://api.aisay.tech.gov.sg/v1/extract",
    headers={
        "Authorization": "Bearer <your-api-key>",
        "Content-Type": "application/json"
    },
    json={
        "file": file_base64,
        "file_type": "pdf",
        "data_classification": "RSN",
        "vlm_prompt": vlm_prompt
    }
)

# 4. Get results
result = response.json()
print(json.dumps(result, indent=2))Copy to clipboardErrorCopied

KIE (Extraction) — cURL

# Encode file to base64
FILE_BASE64=$(base64 -w 0 payslip.pdf)

curl -X POST "https://api.aisay.tech.gov.sg/v1/extract" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "file": "'$FILE_BASE64'",
    "file_type": "pdf",
    "data_classification": "RSN",
    "vlm_prompt": {
      "type": "object",
      "properties": {
        "employee_name": {
          "type": "string",
          "description": "The full name of the employee"
        },
        "net_pay": {
          "type": "string",
          "description": "The final net pay amount"
        }
      },
      "required": ["employee_name", "net_pay"],
      "additionalProperties": false
    }
  }'Copy to clipboardErrorCopied

Classification — Python

import requests
import base64

with open("document.pdf", "rb") as f:
    file_base64 = base64.b64encode(f.read()).decode("utf-8")

document_categories = [
    {
        "category": "PASSPORT",
        "description": "Official international travel document with photo, name, nationality, and passport number"
    },
    {
        "category": "BANK_STATEMENT",
        "description": "A bank statement showing transactions, balances, and account details"
    },
    {
        "category": "NRIC",
        "description": "National Registration Identity Card with name, NRIC number, race, and photo"
    },
    {
        "category": "UNCLASSIFIED",
        "description": "Any document that does not fit the categories above"
    }
]

response = requests.post(
    "https://api.aisay.tech.gov.sg/v1/classify",
    headers={
        "Authorization": "Bearer <your-api-key>",
        "Content-Type": "application/json"
    },
    json={
        "file": file_base64,
        "file_type": "pdf",
        "data_classification": "RSN",
        "document_categories": document_categories
    }
)

print(response.json())Copy to clipboardErrorCopied

Step 5: Use Helper Tools

If you prefer a guided approach, use the free web tools to generate your API code:

• KIE (Extraction): https://tools.getaisay.com/API_Extraction_Helper
• Classification: https://tools.getaisay.com/API_Classification_Helper

These tools let you describe your use case and automatically generate Python and cURL scripts.

JSON Schema Validation

As of February 2026, JSON schema validation is enforced on the APIs. Ensure your vlm_prompt is a valid JSON schema. Key requirements:

• The root must be "type": "object" with a "properties" field
• Each property must have a "type" and "description"
• Use "additionalProperties": false to prevent unexpected fields
• Arrays must include an "items" definition

Error Handling

Next Steps

• Data Extraction (KIE) — Full Guide
• Document Classification — Full Guide
• API Specifications
• Pricing