Direct Transactions

Open Ledger offers a comprehensive Transaction API that allows for direct manipulation of transaction data within your application. This provides you with full control over how transactions are created, categorized, and managed in your financial ledger.

Transaction API Endpoints

The following endpoints are available for managing transactions:

Creating Transactions

To create a new transaction, send a POST request with the transaction details:

1
POST /v1/transactions
2
Authorization: Bearer {access_token}
3
Content-Type: application/json
4
5
{
6
  "entityId": "entity_12345",
7
  "amount": 500.00,
8
  "description": "Invoice payment received",
9
  "debitAccountId": "acc_debit_12345",
10
  "creditAccountId": "acc_credit_12345",
11
  "metadata": {
12
    "receipt_url": "https://example.com/receipts/123.pdf"
13
  }
14
}

Response:

1
{
2
  "id": "txn_123456",
3
  "entityId": "entity_12345",
4
  "timestamp": "2024-01-15T12:00:00Z",
5
  "amount": 500.0,
6
  "description": "Invoice payment received",
7
  "debitAccountId": "acc_debit_12345",
8
  "creditAccountId": "acc_credit_12345",
9
  "status": "PENDING",
10
  "createdAt": "2024-01-15T12:01:00Z",
11
  "updatedAt": "2024-01-15T12:01:00Z",
12
  "metadata": {
13
    "receipt_url": "https://example.com/receipts/123.pdf"
14
  }
15
}

Getting Transactions

Retrieve transactions with optional filtering:

1
GET /v1/transactions?entityId=entity_12345&status=PENDING&limit=10
2
Authorization: Bearer {access_token}

Response:

1
{
2
  "transactions": [
3
    {
4
      "id": "txn_123456",
5
      "entityId": "entity_12345",
6
      "timestamp": "2024-01-15T12:00:00Z",
7
      "amount": 500.0,
8
      "description": "Invoice payment received",
9
      "debitAccountId": "acc_debit_12345",
10
      "creditAccountId": "acc_credit_12345",
11
      "status": "PENDING",
12
      "createdAt": "2024-01-15T12:01:00Z",
13
      "updatedAt": "2024-01-15T12:01:00Z"
14
    }
15
    // More transactions...
16
  ],
17
  "pagination": {
18
    "total": 45,
19
    "page": 1,
20
    "limit": 10,
21
    "hasMore": true
22
  }
23
}

Approving Transactions

To approve a transaction (change status from PENDING to POSTED):

1
PUT /v1/transactions
2
Authorization: Bearer {access_token}
3
Content-Type: application/json
4
5
{
6
  "entityId": "entity_12345",
7
  "transactionId": "txn_123456"
8
}

Response:

1
{
2
  "id": "txn_123456",
3
  "entityId": "entity_12345",
4
  "status": "POSTED",
5
  "updatedAt": "2024-01-15T14:30:00Z",
6
  "message": "Transaction approved successfully"
7
}

Getting Transactions by Month

Retrieve transactions for a specific month:

1
GET /v1/transactions/by-month?entityId=entity_12345&month=1&year=2024
2
Authorization: Bearer {access_token}

Categorizing Transactions

Assign categories to transactions:

1
POST /v1/transactions/categorize
2
Authorization: Bearer {access_token}
3
Content-Type: application/json
4
5
{
6
  "entityId": "entity_12345",
7
  "transactionId": "txn_123456",
8
  "categoryId": "cat_98765"
9
}

Searching Transactions

Search for transactions with advanced filtering:

1
POST /v1/transactions/search
2
Authorization: Bearer {access_token}
3
Content-Type: application/json
4
5
{
6
  "entityId": "entity_12345",
7
  "filters": {
8
    "dateRange": {
9
      "startDate": "2024-01-01",
10
      "endDate": "2024-01-31"
11
    },
12
    "amountRange": {
13
      "min": 100,
14
      "max": 1000
15
    },
16
    "status": ["PENDING", "POSTED"],
17
    "description": "invoice"
18
  },
19
  "pagination": {
20
    "page": 1,
21
    "limit": 20
22
  },
23
  "sort": {
24
    "field": "amount",
25
    "direction": "DESC"
26
  }
27
}

AI Transaction Categorization

Open Ledger provides AI-powered transaction categorization that can automatically suggest ledger accounts for each transaction:

1
POST /v1/transactions/suggest-categories/entity_12345
2
Authorization: Bearer {access_token}
3
Content-Type: application/json
4
5
{
6
  "transactions": [
7
    {
8
      "amount": 125.99,
9
      "direction": "DEBIT",
10
      "description": "AWS Monthly Subscription",
11
      "merchant_name": "Amazon Web Services",
12
      "date": "2023-04-15",
13
      "bank_transaction_id": "tx_12345abcdef"
14
    },
15
    {
16
      "amount": 45.00,
17
      "direction": "DEBIT",
18
      "description": "Office supplies",
19
      "merchant_name": "Staples",
20
      "date": "2023-04-16",
21
      "bank_transaction_id": "tx_67890ghijkl"
22
    }
23
  ]
24
}

Response:

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
      "bank_transaction_id": "tx_12345abcdef"
18
    }
19
    // More categorization results...
20
  ]
21
}

Natural Language Interaction

Interact with your transactions using natural language:

1
GET /v1/transactions/chat?entityId=entity_12345&prompt=Show me all software expenses over $100 from last month
2
Authorization: Bearer {access_token}

Transaction Status Values

Open Ledger supports the following transaction status values:

Best Practices

1. Provide Clear Descriptions: Include detailed, searchable descriptions for each transaction to make reporting more useful.

2. Use Double-Entry Accounting: Always specify both debit and credit accounts for proper ledger balance.

3. Handle Status Properly: Use the appropriate transaction status values and follow proper approval workflows.

4. Leverage AI Categorization: Use the AI categorization capabilities to reduce manual work and improve accuracy.

5. Group Related Transactions: Use metadata to link related transactions for better tracking and reporting.

6. Validate Input Data: Ensure amounts, account IDs, and other data are valid before submitting to the API.

7. Implement Error Handling: Be prepared to handle and retry API failures gracefully.

8. Regular Reconciliation: Periodically approve and reconcile pending transactions to maintain up-to-date entities.

Error Responses

When an error occurs, the API will return an appropriate HTTP status code and a JSON response:

1
{
2
  "success": false,
3
  "error": "Error message describing the issue",
4
  "details": "Additional details about the error (if available)"
5
}

Common HTTP status codes:

• 400 Bad Request: Missing or invalid parameters
• 401 Unauthorized: Authentication failure
• 403 Forbidden: Permission denied
• 404 Not Found: Resource not found
• 500 Internal Server Error: Server-side error