Data Integration

Direct Transactions

Directly import and manage transactions in Open Ledger.

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:

MethodEndpointDescription
GET/v1/transactionsGet transactions with cursor-based pagination
POST/v1/transactionsCreate a new transaction
POST/v1/transactions/editEdit an existing transaction
PUT/v1/transactions/approveApprove one or multiple transactions
DELETE/v1/transactionsDelete a transaction
GET/v1/transactions/by-monthGet transactions for a specific month
POST/v1/transactions/categorizeCategorize a transaction
POST/v1/transactions/searchSearch transactions with advanced filters
GET/v1/transactions/chatNatural language interaction with transactions
GET/v1/transactions/counterpartiesGet entity counterparties and their transaction history

Creating Transactions

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

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

Response:

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

Getting Transactions

Retrieve transactions with cursor-based pagination:

1GET /v1/transactions?entityId=entity_12345&cursor=cursor_abc123&pageSize=10
2Authorization: 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      "debitAccount": {
13        "id": "acc_debit_12345",
14        "name": "Accounts Receivable",
15        "type": "ASSET"
16      },
17      "creditAccount": {
18        "id": "acc_credit_12345",
19        "name": "Sales Revenue",
20        "type": "REVENUE"
21      }
22    }
23  ],
24  "nextCursor": "cursor_def456",
25  "hasMore": true
26}

Approving Transactions

To approve transactions (change status from PENDING to POSTED):

1PUT /v1/transactions/approve?entityId=entity_12345
2Authorization: Bearer {access_token}
3Content-Type: application/json
4
5["txn_123456", "txn_789012"]

Response:

1{
2  "message": "Transactions approved successfully",
3  "approvedTransactions": [
4    {
5      "id": "txn_123456",
6      "status": "POSTED",
7      "updatedAt": "2024-01-15T14:30:00Z"
8    },
9    {
10      "id": "txn_789012",
11      "status": "POSTED",
12      "updatedAt": "2024-01-15T14:30:00Z"
13    }
14  ]
15}

Editing Transactions

Edit an existing transaction:

1POST /v1/transactions/edit
2Authorization: Bearer {access_token}
3Content-Type: application/json
4
5{
6  "id": "txn_123456",
7  "debit_account_id": "acc_new_debit",
8  "credit_account_id": "acc_new_credit",
9  "description": "Updated invoice payment"
10}

Response:

1{
2  "id": "txn_123456",
3  "debit_account_id": "acc_new_debit",
4  "credit_account_id": "acc_new_credit",
5  "description": "Updated invoice payment"
6}

Getting Transactions by Month

Retrieve transactions for a specific month:

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

Response:

1{
2  "month": 1,
3  "year": 2024,
4  "transactions": [
5    {
6      "id": "txn_123456",
7      "description": "Invoice payment received",
8      "amount": 500.0,
9      "timestamp": "2024-01-15T12:00:00Z",
10      "status": "PENDING"
11    }
12  ],
13  "nextCursor": "cursor_jan2024",
14  "hasMore": false
15}

Categorizing Transactions

Assign categories to transactions:

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

Response:

1{
2  "message": "Transaction categorized successfully",
3  "transaction": {
4    "id": "txn_123456",
5    "metadata": {
6      "categoryId": "cat_98765",
7      "categoryName": "Software Expenses"
8    },
9    "updatedAt": "2024-01-15T16:55:30Z"
10  }
11}

Searching Transactions

Search for transactions with advanced filtering:

1POST /v1/transactions/search?entityId=entity_12345
2Authorization: Bearer {access_token}
3Content-Type: application/json
4
5{
6  "query": "invoice",
7  "filters": {
8    "dateFrom": "2024-01-01",
9    "dateTo": "2024-01-31",
10    "amountMin": 100,
11    "amountMax": 1000,
12    "status": "PENDING"
13  },
14  "page": 1,
15  "limit": 20
16}

Response:

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

Natural Language Interaction

Interact with your transactions using natural language:

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

Response:

1{
2  "response": "I found 5 software expenses over $100 from last month, totaling $1,247.50. The largest was a $500 AWS payment on January 15th.",
3  "data": {
4    "transactions": [
5      {
6        "id": "txn_123456",
7        "description": "AWS Monthly Subscription",
8        "amount": 500.0,
9        "timestamp": "2024-01-15T12:00:00Z"
10      }
11    ],
12    "summary": {
13      "total_amount": 1247.50,
14      "transaction_count": 5,
15      "average_amount": 249.50
16    }
17  }
18}

Get Entity Counterparties

Get all counterparties for an entity with their transaction history:

1GET /v1/transactions/counterparties?entityId=entity_12345&pageSize=25
2Authorization: Bearer {access_token}

Response:

1{
2  "success": true,
3  "counterparties": [
4    {
5      "name": "Amazon Web Services",
6      "transactionCount": 12,
7      "firstSeen": "2023-01-15T12:00:00Z",
8      "lastSeen": "2024-01-15T12:00:00Z",
9      "totalAmount": 6000.00,
10      "averageAmount": 500.00
11    },
12    {
13      "name": "Office Depot",
14      "transactionCount": 8,
15      "firstSeen": "2023-02-01T09:30:00Z",
16      "lastSeen": "2024-01-10T16:45:00Z",
17      "totalAmount": 1200.50,
18      "averageAmount": 150.06
19    }
20  ],
21  "nextCursor": "cursor_counterparties",
22  "hasMore": true
23}

AI Transaction Categorization

For AI-powered transaction categorization, use the AI Analysis endpoints instead of the transactions API. See the AI Analysis documentation for details on:

  • /v1/ai/{id}/suggest-categories-vector - Vector-enhanced category suggestions
  • Advanced AI categorization features
  • Machine learning-powered account suggestions

Transaction Status Values

Open Ledger supports the following transaction status values:

StatusDescription
PENDINGTransaction has been created but not yet approved
CLEAREDTransaction has been cleared (e.g., by a bank)
POSTEDTransaction has been approved and recorded in the ledger

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 Analysis endpoints to reduce manual work and improve accuracy.

  5. Use Cursor-Based Pagination: The API uses cursor-based pagination for better performance with large datasets.

  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 ledgers.

Error Responses

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

1{
2  "error": {
3    "code": "VALIDATION_ERROR",
4    "message": "Error message describing the issue"
5  }
6}

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