Skip to main content

​
Overview

The AI Assistant provides a secure, conversational chat experience to query finances, get insights, and trigger actions. Conversations are persisted per user and protected by authentication.

Persistent Conversations

Your chats are saved with full history per conversation.

Context-Aware

Answers leverage your data, preferences, and patterns.

Secure by Default

All endpoints require auth and are isolated per user.

​
Quick Start (App UI)

1

Open Chat

Click the chat button in the app to open the assistant.
2

Start a Conversation

Ask a question or create a new conversation to keep topics organized.
3

Refine & Act

Follow up for deeper insights or ask the assistant to perform supported actions.

​
What the AI Assistant Can Do

Transaction Intelligence

  • Ask natural-language questions about any transaction, category, merchant, or amount range
  • Filter by GST inclusion, business use %, missing receipts, or bill pattern status on demand
  • Run spending analytics (totals, trends, comparisons) with a single prompt

Receipt Control

  • Upload a photo or PDF and let the assistant extract merchant, date, total, and GST automatically
  • Match the file to existing transactions or create a new expense instantly
  • Attach receipts to recurring bill occurrences so every payment stays audit ready

GST & Tax Guidance

  • Query “What is my GST liability this quarter?” for live breakdowns using stored gstRateUsed and gstAmount values
  • Validate deductible status, business-use percentages, and required documentation per locale
  • Generate summaries for tax exports, BAS, or VAT filings without leaving chat

Bulk Automation

  • Commands like “Categorize every Uber ride as Transport” trigger bulk update tools securely
  • Run pattern maintenance (link/unlink bills, mark occurrences paid) while the assistant handles ids
  • Request budgeting insights or forecast renewals and receive structured, exportable answers

​
Receipt Capture Workflow

1

Capture the Receipt

Tap the camera icon on mobile or attach a PDF/image from desktop. Supported formats include JPG, PNG, PDF, HEIC.
2

AI Extraction

The assistant invokes analyze_receipt to pull merchant, amount, date, GST, and line items with ±7 day/±1% matching tolerance.
3

Confirm Action

Choose to link the receipt to a suggested transaction or create a new expense. You can also request a bill pattern link in the same message.
4

Audit Trail

The assistant stores the attachment reference so tax exports, deduction reports, and missing-receipt filters stay accurate.

​
Conversational Patterns & Bills

  • “Show bills missing receipts” lists recurring occurrences lacking documentation.
  • “Mark my electricity bill as paid” updates the occurrence and logs the action.
  • “Forecast my SaaS renewals with GST” combines pattern data and tax rates for forward planning.

​
GST & Tax Expertise

  • Country-specific rates from the CountryTaxRate service answer GST/VAT queries with local terminology.
  • Commands like “Is this expense deductible in Canada?” trigger intelligent tax analysis with reasoning, warnings, and documentation checklists.
  • The assistant can refresh gstIncluded, gstRateUsed, and gstAmount fields when you provide corrected totals.

​
API Endpoints

All endpoints require a valid Authorization: Bearer <token> header. Errors include an X-Error-ID header for support tracing.

​
Send Message

POST /api/chat/message Request body: 
{ "message": "string", "conversationId": "optional" }
Successful response: 
{
  "success": true,
  "data": {
    "conversationId": "uuid",
    "message": {
      "id": "uuid",
      "conversationId": "uuid",
      "role": "assistant",
      "content": "...",
      "createdAt": "ISO-8601"
    },
    "toolsUsed": ["optional", "list"]
  }
}

​
List Conversations

GET /api/chat/conversations Response: 
{ "success": true, "data": [ { "id": "uuid", "title": "AI2Fin Assistant", "messageCount": 0, "createdAt": "ISO-8601", "updatedAt": "ISO-8601" } ] }

​
Create Conversation

POST /api/chat/conversations Response: 
{ "success": true, "data": { "id": "uuid" } }

​
Get Conversation Messages

GET /api/chat/conversations/:id Response: 
{ "success": true, "data": [ { "id": "uuid", "role": "user", "content": "...", "createdAt": "ISO-8601" } ] }

​
Authentication

All endpoints are protected with the platform auth middleware. Provide a valid bearer token. Server-side requires OPENAI_API_KEY configured.

​
Examples

curl -X POST https://app.ai2fin.com/api/chat/message \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Summarize my last 5 expenses","conversationId":"$CID"}'

curl -X GET https://app.ai2fin.com/api/chat/conversations \
  -H "Authorization: Bearer $TOKEN"

curl -X POST https://app.ai2fin.com/api/chat/conversations \
  -H "Authorization: Bearer $TOKEN"

curl -X GET https://app.ai2fin.com/api/chat/conversations/$CID \
  -H "Authorization: Bearer $TOKEN"

​
Notes

  • Responses may include toolsUsed when the assistant invoked internal tools.
  • On failures, the API returns { success: false, error } and sets X-Error-ID.
  • Conversation history is retained for continuity and auditability.