AI Transaction Categorization

Open Ledger uses advanced AI to automatically categorize your financial transactions according to double-entry entitykeeping principles. This system analyzes transaction data, determines the economic nature of each transaction, and suggests the most appropriate debit and credit accounts.

How It Works

Our AI categorization system:

Analyzes transaction details (amount, description, counterparty, etc.)
Enriches the data with AI-generated context about the transaction
Determines the transaction type (expense, revenue, transfer, etc.)
Identifies the most appropriate ledger accounts based on your chart of accounts
Applies double-entry entitykeeping principles to suggest both debit and credit accounts
Provides a confidence score for each suggestion

API Endpoint

The transaction categorization endpoint is available at:

1 POST /v1/transactions/suggest-categories/:entityid
2 Content-Type: application/json
3 Authorization: Bearer your_token_here

Request Parameters

Parameter	Type	Required	Description
entityId	string (path)	Yes	The ID of the entity to categorize in
transactions	array (body)	Yes	Array of transaction objects

Transaction Object Structure

1 {
2   "amount": 125.99,
3   "direction": "DEBIT",
4   "description": "AWS Monthly Subscription",
5   "merchant_name": "Amazon Web Services",
6   "counterparty_name": "AWS",
7   "date": "2023-04-15",
8   "category": ["Software", "Cloud Services"],
9   "payment_channel": "online",
10   "bank_transaction_id": "tx_12345abcdef",
11   "personal_finance_category": {
12     "primary": "BUSINESS_SERVICES",
13     "detailed": "BUSINESS_SOFTWARE"
14   },
15   "location": {
16     "address": "123 Main St",
17     "city": "Seattle",
18     "region": "WA"
19   }
20 }

Example Request

1 {
2   "transactions": [
3     {
4       "amount": 125.99,
5       "direction": "DEBIT",
6       "description": "AWS Monthly Subscription",
7       "merchant_name": "Amazon Web Services",
8       "date": "2023-04-15",
9       "bank_transaction_id": "tx_12345abcdef"
10     },
11     {
12       "amount": 45.0,
13       "direction": "DEBIT",
14       "description": "Office supplies",
15       "merchant_name": "Staples",
16       "date": "2023-04-16",
17       "bank_transaction_id": "tx_67890ghijkl"
18     }
19   ]
20 }

Response

The API returns categorization suggestions for each transaction:

1 {
2   "success": true,
3   "results": [
4     {
5       "suggested_type": "EXPENSE",
6       "suggested_debit_account_id": "acc_12345",
7       "suggested_credit_account_id": "acc_67890",
8       "debit_account_name": "Software Expenses",
9       "credit_account_name": "Checking Account",
10       "confidence": 0.92,
11       "enrichment": {
12         "counterparty_info": "Amazon Web Services (AWS) is a cloud computing provider",
13         "transaction_context": "Monthly subscription payment for cloud services",
14         "likely_business_category": "Software & Technology",
15         "transaction_type": "EXPENSE"
16       },
17       "metadata": {
18         "ledger_accounts": {
19           "debit_account": {
20             "id": "acc_12345",
21             "name": "Software Expenses",
22             "type": "EXPENSE"
23           },
24           "credit_account": {
25             "id": "acc_67890",
26             "name": "Checking Account",
27             "type": "ASSET"
28           },
29           "transaction_type": "EXPENSE"
30         }
31       },
32       "bank_transaction_id": "tx_12345abcdef"
33     },
34     {
35       "suggested_type": "EXPENSE",
36       "suggested_debit_account_id": "acc_24680",
37       "suggested_credit_account_id": "acc_67890",
38       "debit_account_name": "Office Supplies",
39       "credit_account_name": "Checking Account",
40       "confidence": 0.88,
41       "enrichment": {
42         "counterparty_info": "Staples is an office supply retail chain",
43         "transaction_context": "Purchase of office supplies",
44         "likely_business_category": "Office Expenses",
45         "transaction_type": "EXPENSE"
46       },
47       "metadata": {
48         "ledger_accounts": {
49           "debit_account": {
50             "id": "acc_24680",
51             "name": "Office Supplies",
52             "type": "EXPENSE"
53           },
54           "credit_account": {
55             "id": "acc_67890",
56             "name": "Checking Account",
57             "type": "ASSET"
58           },
59           "transaction_type": "EXPENSE"
60         }
61       },
62       "bank_transaction_id": "tx_67890ghijkl"
63     }
64   ],
65   "error": null
66 }

Transaction Types

The AI categorization system identifies several transaction types:

Type	Description	Typical Account Pattern
EXPENSE	Business costs	Debit EXPENSE, Credit ASSET (Cash/Bank)
REVENUE	Income from sales or services	Debit ASSET (Cash/Bank), Credit REVENUE
ASSET_TRANSFER	Moving money between accounts	Debit destination ASSET, Credit source ASSET
LIABILITY_REDUCTION	Paying off debt	Debit LIABILITY, Credit ASSET (Cash/Bank)
REVENUE_REDUCTION	Refunds or discounts	Debit REVENUE, Credit ASSET (Cash/Bank)

Integration Examples

JavaScript

1 const suggestCategories = async (entityId, transactions) => {
2   const response = await fetch(
3     `https://api.openledger.com/v1/transactions/suggest-categories/${entityId}`,
4     {
5       method: "POST",
6       headers: {
7         "Content-Type": "application/json",
8         Authorization: `Bearer ${token}`,
9       },
10       body: JSON.stringify({
11         transactions: transactions,
12       }),
13     }
14   );
15 
16   return await response.json();
17 };
18 
19 // Example usage
20 const transactions = [
21   {
22     amount: 125.99,
23     direction: "DEBIT",
24     description: "AWS Monthly Subscription",
25     merchant_name: "Amazon Web Services",
26     date: "2023-04-15",
27     bank_transaction_id: "tx_12345abcdef",
28   },
29 ];
30 
31 const suggestions = await suggestCategories("entity_123456", transactions);
32 console.log(suggestions);

Python

1 import requests
2 
3 def suggest_categories(token, entity_id, transactions):
4     response = requests.post(
5         f'https://api.openledger.com/v1/transactions/suggest-categories/{entity_id}',
6         headers={
7             'Content-Type': 'application/json',
8             'Authorization': f'Bearer {token}'
9         },
10         json={
11             'transactions': transactions
12         }
13     )
14 
15     return response.json()
16 
17 # Example usage
18 transactions = [
19     {
20         'amount': 125.99,
21         'direction': 'DEBIT',
22         'description': 'AWS Monthly Subscription',
23         'merchant_name': 'Amazon Web Services',
24         'date': '2023-04-15',
25         'bank_transaction_id': 'tx_12345abcdef'
26     }
27 ]
28 
29 suggestions = suggest_categories(token, 'entity_123456', transactions)
30 print(suggestions)

Best Practices

Provide rich transaction data: The more details you provide (descriptions, merchant names, categories), the more accurate the categorization will be.
Review suggestions before approving: While our AI is highly accurate, always review categorization suggestions before finalizing them in your entities.
Batch transactions: For efficiency, send multiple transactions in a single API call rather than individual requests.
Set up a consistent chart of accounts: Having a well-structured chart of accounts improves the AI’s ability to categorize transactions accurately.
Train the system: The more transactions you categorize, the better the system becomes at understanding your business.

How the AI Works

Our categorization system uses several ML/AI techniques:

Transaction enrichment: Uses GPT models to add context about counterparties and transaction purposes
Pattern recognition: Identifies common transaction patterns from your financial history
Double-entry principles: Applies accounting rules to ensure both debit and credit sides are correctly identified
Confidence scoring: Provides a reliability metric for each suggestion