Skip to main content

​
Welcome to AI2Fin API

The AI2Fin API provides enterprise-grade endpoints for financial management, transaction processing, bill automation, and AI-powered tax optimization. Built for scale with support for 100,000+ concurrent users.

OpenAPI Specification

View the complete OpenAPI 3.1 specification

​
Quick Start

​
Authentication

All API endpoints (except registration and login) require authentication via JWT Bearer token or session cookie. 
# Login and receive token
curl -X POST https://api.ai2fin.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "********"
  }'

{
  "success": true,
  "token": "eyJhbGc...truncated",
  "user": {
    "id": "user-uuid",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Smith"
  }
}

​
Using the Token

Include the JWT token in the Authorization header for all subsequent requests: 
curl -X GET https://api.ai2fin.com/api/bank/transactions \
  -H "Authorization: Bearer <YOUR_JWT_TOKEN>"

​
API Features

Bank Transactions

Import, categorize, and manage bank transactions with CSV upload support

AI Classification

Intelligent transaction categorization with tax deduction analysis

Smart Categories (Elite+)

Category sets, multi-category assignments, and transaction history tracking

Bill Automation

Recurring bill patterns with automatic occurrence generation

Custom Rules

Create automation rules with conditions and actions for any entity

Tax Reports

ATO-compliant export with GST/VAT calculations

Analytics

Real-time financial summaries and insights

​
AI Assistant Chat APIs

Use the chat endpoints to power the in-app assistant, automate financial workflows, and ingest receipts securely. See the AI Assistant guide for user experience details.
MethodEndpointPurpose
POST/api/chat/messageSend a message and receive an AI response with tool usage metadata
GET/api/chat/conversationsList conversations for the authenticated user
POST/api/chat/conversationsCreate a new conversation thread
GET/api/chat/conversations/:idFetch the full message history and tool calls
POST/api/chat/uploadUpload files (receipts, invoices, spreadsheets) for analysis
GET/api/chat/files/:userId/:fileNameRetrieve stored attachments with access control
curl -X POST https://api.ai2fin.com/api/chat/message \
  -H "Authorization: Bearer ${AI2FIN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "conversationId": "conv_123",
    "message": "Show expenses missing receipts for September"
  }'
Use /api/chat/upload before calling /api/chat/message when attaching a receipt image or PDF; include the returned assetUrl in the message payload so the assistant can analyze it.

​
GST & Tax APIs

The tax service exposes endpoints for localized GST/VAT rate discovery and precise calculations. These power the User Preferences and Transaction Management experiences.
MethodEndpointPurpose
GET/api/tax/country-ratesFetch all active tax rates grouped by country
GET/api/tax/rates/:countryCodeRetrieve tax profiles for a specific country code (e.g. AU, GB)
POST/api/tax/calculateCalculate GST/VAT amounts for tax-inclusive or tax-exclusive scenarios
curl -X POST https://api.ai2fin.com/api/tax/calculate \
  -H "Authorization: Bearer ${AI2FIN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 220.0,
    "gstIncluded": true,
    "countryCode": "AU",
    "taxType": "GST"
  }'

{
  "success": true,
  "data": {
    "amount": 220,
    "baseAmount": 200,
    "gstAmount": 20,
    "gstIncluded": true,
    "gstRate": 0.1,
    "input": {
      "amount": 220,
      "gstIncluded": true,
      "gstRate": 0.1,
      "countryCode": "AU",
      "taxType": "GST"
    }
  }
}
/api/tax/seed-rates is reserved for provisioning environments. Use the country rate endpoints for read-only access in production clients.

​
Core Concepts

​
Multi-Tenant Architecture

Every API request is scoped to the authenticated user. Data isolation is enforced at the database level with row-level security.

​
Pagination

List endpoints support pagination with standard query parameters:
  • page: Page number (default: 1)
  • limit: Items per page (default: 50, max: 200)
{
  "transactions": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1250,
    "pages": 25
  }
}

​
Rate Limiting

API rate limits vary by subscription tier:
  • Free: 100 requests/15min
  • Starter: 500 requests/15min
  • Professional: 2000 requests/15min
  • Enterprise: Custom limits
Rate limit headers are included in all responses: 
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 487
X-RateLimit-Reset: 1699564800

​
Error Handling

All errors follow a consistent format: 
{
  "success": false,
  "error": "Resource not found",
  "code": "NOT_FOUND"
}
HTTP Status Codes:
  • 200 - Success
  • 201 - Created
  • 400 - Bad Request (validation error)
  • 401 - Unauthorized (missing/invalid token)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Not Found
  • 429 - Rate Limited
  • 500 - Internal Server Error

​
Advanced Features

​
Custom Rules Engine

Create powerful automation rules with:
  • Multiple condition types (contains, equals, regex, etc.)
  • Flexible actions (set category, tax flags, etc.)
  • Priority-based execution
  • Support for transactions, bills, expenses, and patterns

​
GST/VAT Calculations

Built-in support for tax-inclusive and tax-exclusive amounts: 
{
  "amount": 110.00,
  "gstIncluded": true,
  "gstRate": 0.10,
  "gstAmount": 10.00,
  "baseAmount": 100.00
}

​
AI-Powered Features

  • Smart Categorization: ML-based transaction classification
  • Tax Analysis: Automatic deductibility detection
  • Pattern Recognition: Recurring bill detection
  • Intelligent Search: Natural language query across all data

​
Access Control

Enterprise-grade security with:
  • JWT-based authentication with optional JTI validation
  • Cookie-based session management
  • CSRF protection for web clients
  • Row-level security (RLS)
  • NoSQL injection guards
  • Audit logging for compliance

​
Webhooks

Subscribe to real-time events:
  • Transaction imported
  • Bill due soon
  • Pattern detected
  • Rule executed
Webhook support is available on Professional and Enterprise plans.

​
SDKs and Integration

import { AI2FinClient } from '@ai2fin/sdk';

const client = new AI2FinClient({
  apiKey: process.env.AI2FIN_API_KEY,
  baseURL: 'https://api.ai2fin.com'
});

const transactions = await client.transactions.list({
  page: 1,
  limit: 50
});

​
Rate Optimization

Use batch endpoints (/api/bank-batch/update) to update multiple records in a single request and avoid rate limits.

​
Support

All API endpoints return within 200ms (p95) and support 100K+ concurrent users.