API Documentation

PAYE Tax Calculator

Calculate Pay-As-You-Earn tax for individual taxpayers based on annual salary.

Request Parameters

Example Request

{
  "annual_salary": 500000,
  "age": 35,
  "tax_year": "2025/2026"
}

Example Response

{
  "success": true,
  "calculation": {
    "annual_salary": 500000.0,
    "gross_tax": 112532.0,
    "net_tax": 95297.0,
    "rebates_applied": 17235,
    "net_annual_salary": 404703.0,
    "monthly": {
      "gross_salary": 41666.67,
      "tax": 7941.42,
      "net_salary": 33725.25
    },
    "rates": {
      "effective_rate": 19.06,
      "marginal_rate": 31.0
    },
    "tax_year": "2025/2026",
    "calculation_date": "2025-09-24"
  }
}

Integration Example

• Python
• JavaScript
• cURL

import requests

url = "https://your-domain.replit.app/api/calculate-paye"
data = {
    "annual_salary": 500000,
    "age": 35
}

response = requests.post(url, json=data)
result = response.json()

if result["success"]:
    calc = result["calculation"]
    print(f"Monthly Tax: R{calc['monthly']['tax']:,.2f}")
    print(f"Net Salary: R{calc['monthly']['net_salary']:,.2f}")

const response = await fetch('https://your-domain.replit.app/api/calculate-paye', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        annual_salary: 500000,
        age: 35
    })
});

const result = await response.json();
if (result.success) {
    console.log(`Monthly Tax: R${result.calculation.monthly.tax}`);
}

curl -X POST https://your-domain.replit.app/api/calculate-paye \
  -H "Content-Type: application/json" \
  -d '{"annual_salary": 500000, "age": 35}'

Company Tax Calculator

Calculate corporate income tax for South African companies.

Request Parameters

Example Request

{
  "taxable_income": 1000000,
  "company_type": "normal"
}

Example Response

{
  "success": true,
  "calculation": {
    "taxable_income": 1000000.0,
    "tax_rate": 27.0,
    "tax_amount": 270000.0,
    "net_income": 730000.0,
    "company_type": "normal",
    "effective_rate": 27.0
  }
}

VAT Calculator

Calculate VAT amounts for transactions at the standard 15% rate.

Request Parameters

Example Request

{
  "amount": 1000,
  "vat_inclusive": false
}

Example Response

{
  "success": true,
  "calculation": {
    "amount_excl_vat": 1000.0,
    "vat_amount": 150.0,
    "amount_incl_vat": 1150.0,
    "vat_rate": 15.0
  }
}

Universal AI Query

Intelligent routing system that automatically determines whether to perform calculations, search the knowledge base, or provide AI-generated responses based on query intent.

Request Parameters

Query Types Supported

• Tax Calculations: "Calculate PAYE for R500,000 salary"
• Legal Questions: "What is the VAT rate in South Africa?"
• Procedural Guidance: "How do I register for VAT?"
• Document Analysis: "Explain provisional tax requirements"

Example Request

{
  "query": "What are the PAYE tax brackets for 2025?"
}

Example Response

{
  "success": true,
  "intent": "qa",
  "confidence": 0.95,
  "result": {
    "answer": "For the 2025/2026 tax year, the PAYE tax brackets are...",
    "sources": [
      {
        "source": "SARS Tax Tables 2025/2026",
        "similarity": 0.89,
        "text": "Tax bracket information..."
      }
    ],
    "confidence": 0.85
  }
}

Document Analysis

Upload and analyze tax documents using AI to extract key information and provide insights.

Request Format

This endpoint accepts multipart/form-data for file uploads.

Request Parameters

Example Request (Python)

import requests

url = "https://your-domain.replit.app/api/analyze-document"
files = {'file': open('tax_return.pdf', 'rb')}
data = {'analysis_type': 'summary'}

response = requests.post(url, files=files, data=data)
result = response.json()

Example Response

{
  "success": true,
  "analysis": {
    "document_type": "Tax Return",
    "key_information": {
      "tax_year": "2024/2025",
      "taxpayer_type": "Individual",
      "total_income": 650000
    },
    "summary": "This document is an individual tax return...",
    "compliance_notes": [],
    "recommendations": []
  }
}

Knowledge Base Search

Search through the tax knowledge base including legislation, guides, and interpretation notes.

Query Parameters

Example Request

GET /api/search?q=provisional+tax&category=guides&limit=5

Example Response

{
  "success": true,
  "results": [
    {
      "document_id": 5,
      "title": "Guide to Provisional Tax",
      "category": "guides",
      "relevance": 0.92,
      "excerpt": "Provisional tax is a method of paying tax...",
      "tax_year": "2025"
    }
  ],
  "total_results": 5
}

AI Question & Answer

Direct AI-powered Q&A endpoint using RAG (Retrieval Augmented Generation) for accurate tax-related questions with source citations.

Request Parameters

Example Request

{
  "question": "How do I claim home office expenses?"
}

Example Response

{
  "success": true,
  "answer": "To claim home office expenses in South Africa, you must meet specific SARS requirements...",
  "sources": [
    {
      "source": "SARS Home Office Guide",
      "similarity": 0.92,
      "text": "Home office expenses can be claimed if..."
    }
  ],
  "question": "How do I claim home office expenses?",
  "response_time": 1.234
}

Rate Limiting

This endpoint is limited to 20 requests per hour per IP address.

List Documents

Retrieve a list of available documents in the knowledge base.

Query Parameters

Example Response

{
  "success": true,
  "documents": [
    {
      "id": 1,
      "filename": "income_tax_act.pdf",
      "category": "Legislation",
      "processed": true,
      "page_count": 450,
      "upload_date": "2025-09-01"
    }
  ],
  "total": 25
}