Ledger Management | Open Ledger Documentation

Open Ledger provides comprehensive APIs for managing entities (ledgers) and their financial transactions. This guide covers how to create, update, and delete entities, as well as how to work with transactions within those entities.

Entities

An “entity” in Open Ledger represents a financial ledger for a business entity. It contains all financial transactions and accounts for that entity.

Creating an Entity

To create a new entity, use the following endpoint:

1 POST /v1/entity
2 Content-Type: application/json
3 Authorization: Bearer {access_token}
4 
5 {
6   "legalName": "Acme Corporation",
7   "tin": "12-3456789",
8   "usState": "CA",
9   "entityType": "LLC",
10   "phoneNumber": "+14155551234",
11   "address": {
12     "line1": "123 Main Street",
13     "line2": "Suite 100",
14     "city": "San Francisco",
15     "state": "CA",
16     "postalCode": "94105",
17     "country": "US"
18   }
19 }

Retrieving Entity Details

To get the details of a specific entity:

1 GET /v1/entity?entityId=entity_123abc
2 Authorization: Bearer {access_token}

Updating an Entity

To update an existing entity:

1 PUT /v1/entity?entityId=entity_123abc
2 Content-Type: application/json
3 Authorization: Bearer {access_token}
4 
5 {
6   "legalName": "Acme Corporation LLC",
7   "phoneNumber": "+14155559876"
8 }

Deleting an entity

To delete an entity:

1 DELETE /v1/entities?entityId=entity_123abc
2 Authorization: Bearer {access_token}

Transactions

Transactions record financial activities within an entity. Each transaction represents a financial event such as a sale, purchase, payment, or receipt.

Adding Transactions

To add a new transaction:

1 POST /v1/transactions
2 Content-Type: application/json
3 Authorization: Bearer {access_token}
4 
5 {
6   "entityId": "entity_123abc",
7   "date": "2024-01-15",
8   "description": "Software Subscription",
9   "amount": 99.99,
10   "type": "EXPENSE",
11   "categoryId": "cat_5678",
12   "notes": "Monthly subscription for accounting software",
13   "source": "bank_import",
14   "metadata": {
15     "bank_reference_id": "tx_98765",
16     "merchant_info": {
17       "name": "SaaS Company Inc",
18       "category": "Software"
19     }
20   }
21 }

Retrieving Transactions

To retrieve transactions for an entity:

1 GET /v1/transactions?entityId=entity_123abc&limit=25&offset=0
2 Authorization: Bearer {access_token}

You can filter transactions using various parameters:

1 GET /v1/transactions?entityId=entity_123abc&startDate=2024-01-01&endDate=2024-01-31&type=EXPENSE&minAmount=50&maxAmount=1000
2 Authorization: Bearer {access_token}

Updating a Transaction

To update an existing transaction:

1 PUT /v1/transactions
2 Content-Type: application/json
3 Authorization: Bearer {access_token}
4 
5 {
6   "entityId": "entity_123abc",
7   "transactionId": "txn_123456",
8   "description": "Annual Software Subscription",
9   "amount": 1099.99,
10   "notes": "Yearly subscription for accounting software"
11 }

Deleting a Transaction

To delete a transaction:

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

Bulk Operations

Open Ledger supports bulk operations for transactions:

Bulk Create

1 POST /v1/transactions/bulk
2 Content-Type: application/json
3 Authorization: Bearer {access_token}
4 
5 {
6   "entityId": "entity_123abc",
7   "transactions": [
8     {
9       "date": "2024-01-15",
10       "description": "Office Supplies",
11       "amount": 250.75,
12       "type": "EXPENSE",
13       "categoryId": "cat_5678"
14     },
15     {
16       "date": "2024-01-15",
17       "description": "Client Payment",
18       "amount": 5000.00,
19       "type": "REVENUE",
20       "categoryId": "cat_1234"
21     }
22   ]
23 }

Bulk Update

1 PUT /v1/transactions/bulk
2 Content-Type: application/json
3 Authorization: Bearer {access_token}
4 
5 {
6   "entityId": "entity_123abc",
7   "transactions": [
8     {
9       "transactionId": "txn_123456",
10       "categoryId": "cat_9876"
11     },
12     {
13       "transactionId": "txn_789012",
14       "categoryId": "cat_5432"
15     }
16   ]
17 }

Bulk Delete

1 DELETE /v1/transactions/bulk
2 Content-Type: application/json
3 Authorization: Bearer {access_token}
4 
5 {
6   "entityId": "entity_123abc",
7   "transactionIds": ["txn_123456", "txn_789012"]
8 }

Bank Connection

Open Ledger allows you to connect bank accounts to automatically import transactions:

Creating a Bank Link

1 GET /v1/banks/create-link?entityId=entity_123abc
2 Authorization: Bearer {access_token}

Response:

1 {
2   "link_token": "link-sandbox-abc123def456",
3   "expiration": "2024-01-31T23:59:59Z"
4 }

Adding Bank Accounts

1 PUT /v1/banks/accounts?entityId=entity_123abc
2 Content-Type: application/json
3 Authorization: Bearer {access_token}
4 
5 {
6   "public_token": "public-sandbox-abc123def456"
7 }

Code Example

1 import { OpenLedger } from "@openledger/sdk";
2 
3 const openledger = new OpenLedger({
4   apiKey: "your-api-key",
5 });
6 
7 // Create a new entity
8 const entity = await openledger.createentity({
9   legalName: "Acme Corporation",
10   tin: "12-3456789",
11   usState: "CA",
12   entityType: "LLC",
13   phoneNumber: "+14155551234",
14   address: {
15     line1: "123 Main Street",
16     line2: "Suite 100",
17     city: "San Francisco",
18     state: "CA",
19     postalCode: "94105",
20     country: "US",
21   },
22 });
23 
24 // Add a transaction
25 const transaction = await openledger.createTransaction({
26   entityId: entity.id,
27   date: "2024-01-15",
28   description: "Software Subscription",
29   amount: 99.99,
30   type: "EXPENSE",
31   categoryId: "cat_5678",
32 });
33 
34 // Retrieve transactions
35 const transactions = await openledger.getTransactions({
36   entityId: entity.id,
37   startDate: "2024-01-01",
38   endDate: "2024-01-31",
39   limit: 25,
40 });
41 
42 // Generate a bank link token
43 const linkToken = await openledger.createBankLink({
44   entityId: entity.id,
45 });

Best Practices

Regular Reconciliation: Regularly reconcile transactions with external sources
Consistent Categorization: Maintain a consistent categorization scheme for transactions
Transaction Documentation: Add detailed notes and metadata to transactions
Backup Before Bulk Operations: Create a backup before performing bulk operations
Use Idempotency Keys: For critical operations, use idempotency keys to prevent duplication
Handle Pagination: When retrieving large datasets, implement pagination correctly
Error Handling: Implement robust error handling for all API calls