Reports | Open Ledger Documentation

The reports endpoints allow you to generate, customize, and retrieve financial reports for your entities. These reports provide insights into your financial health and performance.

Report Objects

A report in Open Ledger represents a financial statement or analysis that provides insights into your entity’s financial status. The API returns comprehensive financial data including hierarchical account structures, detailed balances, and PDF generation capabilities.

Available Reports

Open Ledger provides the following standard financial reports:

Balance Sheet: Shows assets, liabilities, and equity at a specific point in time
Income Statement (Profit & Loss): Shows revenue, expenses, and profit over a period of time
Cash Flow Statement: Shows changes in cash position over a period of time
General Ledger: Shows all transactions across all accounts
Trial Balance: Shows the balance of all accounts at a specific point in time

Generate Financial Reports

Generate comprehensive financial statements for an entity, including balance sheet, income statement, and cash flow statement.

1 GET /v1/reports/generate?entityId={entity_id}
2 Authorization: Bearer {access_token}

Query Parameters

Parameter	Type	Description
`entityId`	string	ID of the entity to generate reports for (required)
`month`	integer	Month number (1-12)
`year`	integer	Year (e.g., 2024)
`type`	string	Type of report: INCOME, BALANCE, CASHFLOW
`ledgerId`	string	Optional ledger ID (if not provided, will use entityId)

Response (JSON format)

1 {
2   "reportPeriod": {
3     "month": 3,
4     "year": 2024,
5     "startDate": "2024-03-01T00:00:00Z",
6     "endDate": "2024-03-31T23:59:59Z"
7   },
8   "balanceSheet": {
9     "hierarchical": {
10       "assets": [
11         {
12           "id": "ASSET-CASH",
13           "name": "Cash",
14           "type": "ASSET",
15           "financialType": "CASH",
16           "balance": 10500.0,
17           "children": [
18             {
19               "id": "Cash-ASSET",
20               "name": "Cash",
21               "type": "ASSET", 
22               "financialType": "CASH",
23               "balance": 10500.0,
24               "parentId": "ASSET-CASH",
25               "level": 1
26             }
27           ],
28           "parentId": null,
29           "level": 0,
30           "isCategory": true
31         }
32       ],
33       "liabilities": [],
34       "equity": [],
35       "totals": {
36         "totalAssets": 150000.0,
37         "totalLiabilities": 75000.0,
38         "totalEquity": 75000.0,
39         "liabilitiesAndEquity": 150000.0
40       }
41     },
42     "totalCurrentAssets": 135000.0,
43     "totalNonCurrentAssets": 15000.0,
44     "totalAssets": 150000.0,
45     "totalCurrentLiabilities": 45000.0,
46     "totalNonCurrentLiabilities": 30000.0,
47     "totalLiabilities": 75000.0,
48     "totalEquity": 75000.0,
49     "liabilitiesAndEquity": 150000.0
50   },
51   "incomeStatement": {
52     "hierarchical": {
53       "revenue": [
54         {
55           "id": "REVENUE-SALES",
56           "name": "Sales Revenue",
57           "type": "REVENUE",
58           "balance": 50000.0,
59           "children": [],
60           "level": 0
61         }
62       ],
63       "expenses": [
64         {
65           "id": "EXPENSE-OPERATING",
66           "name": "Operating Expenses",
67           "type": "EXPENSE", 
68           "balance": 30000.0,
69           "children": [],
70           "level": 0
71         }
72       ],
73       "totals": {
74         "totalRevenue": 50000.0,
75         "totalExpenses": 30000.0,
76         "netIncome": 20000.0
77       }
78     },
79     "revenue": 50000.0,
80     "expenses": 30000.0,
81     "grossProfit": 50000.0,
82     "operatingIncome": 20000.0,
83     "incomeBeforeTax": 20000.0,
84     "netIncome": 20000.0
85   },
86   "cashFlowStatement": {
87     "hierarchical": {
88       "operatingActivities": {
89         "netIncome": 20000.0,
90         "adjustments": {
91           "depreciation": 2000.0,
92           "changeInAccountsReceivable": -5000.0,
93           "changeInInventory": 1000.0,
94           "changeInAccountsPayable": 3000.0,
95           "changeInAccruedLiabilities": 500.0
96         }
97       },
98       "investingActivities": {
99         "purchaseOfFixedAssets": -10000.0,
100         "purchaseOfInvestments": 0.0,
101         "saleOfInvestments": 0.0
102       },
103       "financingActivities": {
104         "proceedsFromDebt": 5000.0,
105         "repaymentOfDebt": -2000.0,
106         "issuanceOfStock": 0.0,
107         "dividendsPaid": -1000.0
108       },
109       "totals": {
110         "totalOperatingActivities": 21500.0,
111         "totalInvestingActivities": -10000.0,
112         "totalFinancingActivities": 2000.0,
113         "netChangeInCash": 13500.0
114       }
115     },
116     "netCashFromOperatingActivities": 21500.0,
117     "netCashFromInvestingActivities": -10000.0,
118     "netCashFromFinancingActivities": 2000.0,
119     "netChangeInCash": 13500.0
120   },
121   "reconciliation": {
122     "plaidAccountsTotal": 10500.0,
123     "ledgerCashBalance": 10500.0,
124     "difference": 0.0,
125     "plaidAccounts": [
126       {
127         "id": "plaid_acc_123",
128         "name": "Chase Checking",
129         "balance": 10500.0,
130         "type": "CHECKING"
131       }
132     ]
133   },
134   "accountHierarchy": [
135     {
136       "id": "ASSET",
137       "name": "Assets", 
138       "type": "ASSET",
139       "children": [],
140       "level": 0
141     }
142   ],
143   "pdf_urls": {
144     "profit_loss": "https://storage.openledger.com/reports/pl-123456.pdf",
145     "balance_sheet": "https://storage.openledger.com/reports/bs-123456.pdf",
146     "cash_flow": "https://storage.openledger.com/reports/cf-123456.pdf"
147   }
148 }

Generate a General Ledger Report

Generate a general ledger report, which includes a detailed view of all accounts and their transactions.

1 GET /v1/reports/general-ledger?entityId={entity_id}
2 Authorization: Bearer {access_token}

Query Parameters

Parameter	Type	Description
`entityId`	string	ID of the entity to generate reports for (required)
`month`	integer	Month number (1-12) for the report period
`year`	integer	Year (e.g., 2024) for the report period

Response (JSON format)

1 {
2   "accounts": [
3     {
4       "name": "Cash",
5       "type": "ASSET",
6       "financialType": "CASH",
7       "accountCode": 1010,
8       "subTypeCode": 1010,
9       "balance": {
10         "debits_pending": "1000.00",
11         "debits_posted": "11000.00",
12         "credits_pending": "0.00",
13         "credits_posted": "500.00",
14         "timestamp": "2024-01-15T00:00:00Z"
15       },
16       "metadata": {
17         "reportPeriod": "2024-03"
18       }
19     }
20     // Additional accounts...
21   ],
22   "entries": [
23     {
24       "id": "entry_123456",
25       "ledger_id": "ldgr_789012",
26       "debit_account_id": "acc_cash",
27       "credit_account_id": "acc_revenue",
28       "amount": 1000.0,
29       "description": "Service payment received",
30       "status": "POSTED",
31       "created_at": "2024-01-15T14:30:00Z"
32     }
33     // Additional entries...
34   ],
35   "pdf_url": "https://storage.openledger.com/reports/gl-123456.pdf",
36   "hierarchy": {
37     "assets": [
38       {
39         "id": "ASSET-CASH",
40         "name": "Cash",
41         "type": "ASSET",
42         "financialType": "CASH",
43         "balance": 11500.0,
44         "children": [
45           {
46             "id": "Cash-ASSET",
47             "name": "Cash",
48             "type": "ASSET",
49             "financialType": "CASH",
50             "balance": 11500.0,
51             "parentId": "ASSET-CASH",
52             "level": 1
53           }
54         ],
55         "parentId": null,
56         "level": 0,
57         "isCategory": true
58       }
59     ],
60     "liabilities": [],
61     "equity": [],
62     "revenue": [],
63     "expenses": []
64   }
65 }

Report Customization and Filters

You can customize reports with these additional parameters:

Parameter	Description
`entityId`	Required entity identifier for all reports
`month`	Specific month for periodic reports (1-12)
`year`	Specific year for periodic reports
`type`	Report type: INCOME, BALANCE, or CASHFLOW
`ledgerId`	Optional ledger ID override

Error Handling

Status Code	Description
`400`	Bad Request - Missing entityId or invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Entity or ledger not found
`422`	Unprocessable Entity - Invalid report configuration
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

Example error response:

1 {
2   "error": "entityId is required"
3 }

Best Practices

Regular reporting: Generate and save reports at consistent intervals (monthly, quarterly, yearly) for historical comparison.
Export formats: Choose appropriate formats based on your needs:
- JSON: For programmatic analysis and integration
- PDF: For presentation and sharing
Date ranges: Use consistent date ranges for comparable reports by specifying month and year parameters.
Data quality: Ensure all transactions are properly categorized before generating reports.
Caching: Cache report results when appropriate to improve performance for frequently accessed reports.

Next Steps

Transaction Categories

Manage chart of accounts for proper categorization

Transactions

Record financial transactions