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

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.