API OverviewExpanded Resources

Ledger Accounts

Manage chart of accounts with the Open Ledger API.

The ledger accounts endpoints allow you to create, retrieve, update, and manage the chart of accounts for your entities. Ledger accounts represent the different categories used to classify financial transactions.

Ledger Account Objects

A ledger account in Open Ledger represents a specific category in your chart of accounts. Each account has the following properties:

1{
2  "id": "acc_123abc",
3  "name": "Cash",
4  "type": "ASSET",
5  "financial_type": "CASH",
6  "sub_type": "PRIMARY_CASH",
7  "sub_type_code": 1010,
8  "entity_id": "entity_789xyz",
9  "ledger_id": "ldgr_456def",
10  "parent_account_id": null,
11  "top_level": true,
12  "metadata": {
13    "description": "Main operating cash account",
14    "tags": ["operating", "liquid"]
15  },
16  "created_at": "2024-01-01T00:00:00Z",
17  "updated_at": "2024-01-15T00:00:00Z"
18}

Account Types

Open Ledger supports the following account types:

  • ASSET: Resources owned by the entity (cash, accounts receivable, inventory)
  • LIABILITY: Obligations owed by the entity (accounts payable, loans)
  • EQUITY: Owners’ interests in the entity (capital, retained earnings)
  • REVENUE: Income earned from business activities (sales, service fees)
  • EXPENSE: Costs incurred in business operations (rent, salaries, utilities)

Financial types provide more specific categorization within these broader types, such as:

  • CASH, ACCOUNTS_RECEIVABLE, INVENTORY (Asset subtypes)
  • ACCOUNTS_PAYABLE, SHORT_TERM_DEBT (Liability subtypes)
  • RETAINED_EARNINGS, OWNER_EQUITY (Equity subtypes)
  • SALES, SERVICE_REVENUES (Revenue subtypes)
  • PAYROLL_EXPENSES, RENT_EXPENSES (Expense subtypes)

Create a Ledger Account

Create a new ledger account in the entity’s chart of accounts.

1POST /v1/accounts
2X-entity-ID: entity_123abc
3Authorization: Bearer {access_token}
4Content-Type: application/json

Request Body

FieldTypeDescription
namestringAccount name
typeenumAccount type (ASSET, LIABILITY, EQUITY, REVENUE, EXPENSE)
financial_typeenumSpecific financial categorization
sub_type_codeintegerNumeric code for the account subtype
parent_account_idstringParent account ID for hierarchical structure (optional)
top_levelbooleanWhether the account is a top-level account (default: false)
metadataobjectAdditional metadata for the account (optional)
1{
2  "name": "Marketing Expenses",
3  "type": "EXPENSE",
4  "financial_type": "ADVERTISING_EXPENSES",
5  "sub_type_code": 5020,
6  "parent_account_id": "acc_expenses",
7  "top_level": false,
8  "metadata": {
9    "description": "General marketing and advertising expenses"
10  }
11}

Response

1{
2  "id": "acc_marketing",
3  "name": "Marketing Expenses",
4  "type": "EXPENSE",
5  "financial_type": "ADVERTISING_EXPENSES",
6  "sub_type_code": 5020,
7  "entity_id": "entity_123abc",
8  "ledger_id": "ldgr_456def",
9  "parent_account_id": "acc_expenses",
10  "top_level": false,
11  "metadata": {
12    "description": "General marketing and advertising expenses"
13  },
14  "created_at": "2024-01-15T10:30:00Z",
15  "updated_at": "2024-01-15T10:30:00Z"
16}

List Ledger Accounts

Retrieve a list of ledger accounts for an entity.

1GET /v1/accounts
2X-entity-ID: entity_123abc
3Authorization: Bearer {access_token}

Query Parameters

ParameterTypeDescription
typestringFilter by account type
financial_typestringFilter by financial type
parent_account_idstringFilter by parent account
top_levelbooleanFilter to only top-level accounts
pageintegerPage number for pagination (default: 1)
limitintegerItems per page (default: 25, max: 100)

Response

1{
2  "data": [
3    {
4      "id": "acc_cash",
5      "name": "Cash",
6      "type": "ASSET",
7      "financial_type": "CASH",
8      "sub_type_code": 1010,
9      "entity_id": "entity_123abc",
10      "ledger_id": "ldgr_456def",
11      "parent_account_id": null,
12      "top_level": true,
13      "metadata": null,
14      "created_at": "2024-01-01T00:00:00Z",
15      "updated_at": "2024-01-15T00:00:00Z"
16    }
17    // Additional accounts...
18  ],
19  "meta": {
20    "total": 87,
21    "page": 1,
22    "limit": 25,
23    "pages": 4
24  }
25}

Get a Ledger Account

Retrieve a specific ledger account by ID.

1GET /v1/accounts/{id}
2X-entity-ID: entity_123abc
3Authorization: Bearer {access_token}

Path Parameters

ParameterTypeDescription
idstringLedger account ID

Query Parameters

ParameterTypeDescription
include_transactionsbooleanInclude recent transactions (default: false)
transactions_limitintegerNumber of transactions to include (default: 10, max: 50)

Response

1{
2  "id": "acc_cash",
3  "name": "Cash",
4  "type": "ASSET",
5  "financial_type": "CASH",
6  "sub_type_code": 1010,
7  "entity_id": "entity_123abc",
8  "ledger_id": "ldgr_456def",
9  "parent_account_id": null,
10  "top_level": true,
11  "metadata": null,
12  "transactions": [
13    {
14      "id": "txn_123",
15      "timestamp": "2024-01-15T14:22:00Z",
16      "description": "Office Supplies Purchase",
17      "amount": 250.0,
18      "direction": "CREDIT"
19    }
20    // Additional transactions...
21  ],
22  "created_at": "2024-01-01T00:00:00Z",
23  "updated_at": "2024-01-15T00:00:00Z"
24}

Update a Ledger Account

Update an existing ledger account.

1PUT /v1/accounts/{id}
2X-entity-ID: entity_123abc
3Authorization: Bearer {access_token}
4Content-Type: application/json

Path Parameters

ParameterTypeDescription
idstringLedger account ID

Request Body

FieldTypeDescription
namestringAccount name
parent_account_idstringParent account ID
financial_typeenumFinancial type category
sub_type_codeintegerNumeric code for the account
metadataobjectAdditional metadata for the account
1{
2  "name": "Marketing and Advertising Expenses",
3  "sub_type_code": 5025,
4  "metadata": {
5    "description": "Updated description for marketing expenses",
6    "tags": ["marketing", "advertising", "promotion"]
7  }
8}

Response

Returns the updated ledger account object.

Delete a Ledger Account

Delete a ledger account.

1DELETE /v1/accounts/{id}
2X-entity-ID: entity_123abc
3Authorization: Bearer {access_token}

You can only delete accounts that have no transactions and no child accounts.

Path Parameters

ParameterTypeDescription
idstringLedger account ID

Response

A successful request will return a 204 No Content response with no body.

Get Ledger Account Balance

Get the current balance for a ledger account.

1GET /v1/accounts/{id}/balance
2X-entity-ID: entity_123abc
3Authorization: Bearer {access_token}

Path Parameters

ParameterTypeDescription
idstringLedger account ID

Query Parameters

ParameterTypeDescription
as_ofstringGet balance as of a specific date (YYYY-MM-DD)
include_child_accountsbooleanInclude balances of child accounts (default: true)

Response

1{
2  "account_id": "acc_cash",
3  "balance": {
4    "debits_pending": "1000.00",
5    "debits_posted": "11000.00",
6    "credits_pending": "0.00",
7    "credits_posted": "500.00",
8    "timestamp": "2024-01-15T00:00:00Z"
9  },
10  "net_balance": "10500.00",
11  "currency": "USD",
12  "as_of": "2024-01-15",
13  "child_account_balances": [
14    {
15      "account_id": "acc_petty_cash",
16      "balance": {
17        "debits_posted": "500.00",
18        "credits_posted": "0.00",
19        "net_balance": "500.00"
20      }
21    },
22    {
23      "account_id": "acc_main_checking",
24      "balance": {
25        "debits_posted": "10500.00",
26        "credits_posted": "500.00",
27        "net_balance": "10000.00"
28      }
29    }
30  ]
31}

Get Ledger Account Transactions

Get transactions for a specific ledger account.

1GET /v1/accounts/{id}/transactions
2X-entity-ID: entity_123abc
3Authorization: Bearer {access_token}

Path Parameters

ParameterTypeDescription
idstringLedger account ID

Query Parameters

ParameterTypeDescription
from_datestringStart date (YYYY-MM-DD)
to_datestringEnd date (YYYY-MM-DD)
pageintegerPage number for pagination (default: 1)
limitintegerItems per page (default: 25, max: 100)
statusstringFilter by transaction status

Response

1{
2  "data": [
3    {
4      "id": "txn_123",
5      "timestamp": "2024-01-15T14:22:00Z",
6      "description": "Office Supplies Purchase",
7      "amount": 250.0,
8      "direction": "CREDIT",
9      "status": "CLEARED",
10      "metadata": {
11        "receipt_url": "https://storage.example.com/receipts/123.pdf"
12      }
13    }
14    // Additional transactions...
15  ],
16  "meta": {
17    "total": 42,
18    "page": 1,
19    "limit": 25,
20    "pages": 2
21  }
22}

Import Chart of Accounts

Import a chart of accounts from a template or file.

1POST /v1/accounts/import
2X-entity-ID: entity_123abc
3Authorization: Bearer {access_token}
4Content-Type: application/json

Request Body

FieldTypeDescription
sourcestringImport source (“template” or “file”)
template_idstringID of the template to use (when source is “template”)
filebase64Base64-encoded file content (when source is “file”)
file_formatstringFormat of the file (“csv”, “xlsx”)
1{
2  "source": "template",
3  "template_id": "tmpl_standard_business"
4}

Response

1{
2  "import_id": "imp_123abc",
3  "status": "completed",
4  "accounts_created": 75,
5  "accounts_skipped": 0,
6  "errors": []
7}

Error Handling

Status CodeDescription
400Bad Request - Invalid input parameters
401Unauthorized - Invalid or missing API key
403Forbidden - Insufficient permissions
404Not Found - Ledger account not found
409Conflict - Account cannot be deleted due to existing transactions or child accounts
429Too Many Requests - Rate limit exceeded
500Internal Server Error

Best Practices

  1. Consistent account structure: Use a standardized chart of accounts across all entities.

  2. Unique account codes: Ensure each account has a unique numeric code following a logical numbering system.

  3. Hierarchical organization: Use parent-child relationships to create meaningful account hierarchies.

  4. Use categories: Create category accounts to group related accounts together.

  5. Standard templates: Use standard templates for common business types to get started quickly.

Next Steps

Transactions

Record financial transactions

Reports

Generate financial reports