Skip to main content

​
Welcome to AI2Fin API

The AI2Fin API provides endpoints for financial management, transaction processing, bill automation, and AI-powered tax optimization.

OpenAPI Specification

View the complete OpenAPI 3.1 specification

​
Quick Start

​
Authentication Methods

AI2Fin API supports two authentication methods:
Standard authentication for web and mobile apps

​
Method 1: Bearer Token (OAuth Login)

All API endpoints (except registration and login) require authentication. Sign in to receive a bearer token, then send it in the Authorization header on every request. 
# Sign in and receive a token
curl -X POST https://api.ai2fin.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "********"
  }'

{
  "success": true,
  "token": "<YOUR_TOKEN>",
  "user": {
    "id": "user-uuid",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Smith"
  }
}
Using your token: 
curl -X GET https://api.ai2fin.com/api/bank/transactions \
  -H "Authorization: Bearer <YOUR_TOKEN>"

​
Method 2: API Key

API keys are ideal for:
  • MCP integrations
  • Server-to-server automation
  • Custom integrations and webhooks
  • Testing and development

Create API Key

Generate a new API key from the AI2Fin dashboard.
Generate an API key: Create an API key using your bearer token: 
curl -X POST https://api.ai2fin.com/api/api-keys \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My MCP Integration",
    "scopes": ["mcp:full"],
    "expiresInDays": 90
  }'
Response: 
{
  "id": "key_...",
  "key": "<YOUR_API_KEY>",
  "name": "My MCP Integration",
  "scopes": ["mcp:full"],
  "expiresAt": "2026-04-01T00:00:00Z",
  "createdAt": "2026-01-01T00:00:00Z"
}
Your API key is shown only once at creation. Copy and store it somewhere safe — you won’t be able to view it again.
Default Scope: If you don’t specify scopes, the key defaults to ["mcp:full"].
Using an API key: Send your API key in either the X-API-Key header or the Authorization: Bearer header. 
# X-API-Key header
curl -X GET https://api.ai2fin.com/api/bank/transactions \
  -H "X-API-Key: <YOUR_API_KEY>"

# Authorization header
curl -X GET https://api.ai2fin.com/api/bank/transactions \
  -H "Authorization: Bearer <YOUR_API_KEY>"
Keep your API keys safe:
  • Store keys securely (for example, in environment variables or a secret manager)
  • Rotate keys periodically and revoke any key you believe is exposed
  • Grant only the scopes each integration actually needs
API Key Scopes:
  • mcp:read - Read-only MCP operations
  • mcp:tools:list - List available tools
  • mcp:tools:call - Execute tools (read-only)
  • mcp:resources:read - Read resources
  • mcp:full - Full MCP access (read + write)

​
Connecting an MCP client

AI2Fin exposes a Model Context Protocol (MCP) endpoint so AI assistants and automation clients can work with your financial data securely. Authenticate with an API key, then use standard JSON-RPC methods such as tools/list and tools/call. 
# List the MCP tools available to your key
curl -X POST https://api.ai2fin.com/mcp \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

​
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

Tax-ready exports with GST/VAT calculations included

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 <YOUR_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

These endpoints provide localized GST/VAT/Sales Tax rate lookup and accurate tax calculations for transactions. They power the User Preferences and Transaction Management experiences.
MethodEndpointPurpose
GET/api/tax/country-ratesList active tax rates grouped by country
GET/api/tax/rates/:countryCodeGet the tax profile for a country code (e.g. AU, GB)
POST/api/tax/calculateCalculate the tax amount for a tax-inclusive or tax-exclusive price
curl -X POST https://api.ai2fin.com/api/tax/calculate \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 220.0,
    "taxIncluded": true,
    "countryCode": "AU"
  }'
The response returns the calculated tax, the pre-tax amount, and the rate applied for the country — so you always see exactly how the figure was reached. 
{
  "success": true,
  "data": {
    "total": 220,
    "subtotal": 200,
    "tax": 20,
    "rate": 0.1,
    "countryCode": "AU"
  }
}

​
Core Concepts

​
Data Scoping

Every API request is scoped to the authenticated user. You can only ever read and write your own data — accounts are isolated from one another.

​
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

The API is rate limited to keep the platform fast and reliable for everyone. Limits scale with your subscription tier, with higher allowances on paid and Enterprise plans. If you exceed your limit, the API responds with 429 Too Many Requests — pause briefly and retry. Each response includes standard X-RateLimit-* headers so your client can see its remaining allowance and when it resets.

​
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 both tax-inclusive and tax-exclusive amounts. Send a price and a country, and the API returns the tax, the pre-tax subtotal, and the rate applied — ready to display or store against a transaction.

​
AI-Powered Features

  • Smart Categorization: Transactions are sorted into the right categories automatically
  • Tax Analysis: Likely deductions are surfaced for you to review
  • Pattern Recognition: Recurring bills and subscriptions are detected
  • Intelligent Search: Ask questions in plain language across all your data

​
Access Control

  • Bearer token authentication for user sessions (from OAuth login)
  • API key authentication for server-to-server and automation
  • Per-account data isolation — you only ever access your own records
  • Activity is logged to support compliance and account security
Authentication Headers:
  • Authorization: Bearer <YOUR_TOKEN> - bearer token from OAuth login or an API key
  • X-API-Key: <YOUR_API_KEY> - API key (recommended for MCP)

​
Webhooks

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

​
Calling the API

The AI2Fin REST API works with any HTTP client. Authenticate with a bearer token or an API key, then call the JSON endpoints directly. 
# Using a bearer token (from OAuth login)
curl "https://api.ai2fin.com/api/bank/transactions?page=1&limit=50" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

# Or using an API key
curl "https://api.ai2fin.com/api/bank/transactions?page=1&limit=50" \
  -H "X-API-Key: <YOUR_API_KEY>"
Official SDKs — coming soon. First-party client libraries are planned to make integration even faster. In the meantime, the REST and MCP endpoints above work with any standard HTTP or MCP client.

​
Support