API OverviewExpanded Resources

Reports

Generate financial reports with the Open Ledger API.

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:

1{
2  "id": "rep_123abc",
3  "reportType": "balance_sheet",
4  "periodStart": "2024-01-01T00:00:00Z",
5  "periodEnd": "2024-01-31T23:59:59Z",
6  "generatedAt": "2024-02-01T10:00:00Z",
7  "content": {
8    "assets": {
9      "total": "125000.00",
10      "current_assets": { ... },
11      "fixed_assets": { ... }
12    },
13    "liabilities": { ... },
14    "equity": { ... }
15  },
16  "pdf_url": "https://storage.openledger.com/reports/bs-123456.pdf"
17}

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.

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

Query Parameters

ParameterTypeDescription
monthintegerMonth number (1-12)
yearintegerYear (e.g., 2024)
reportTypestringType of report to generate (balance_sheet, income_statement, cash_flow)
formatstringResponse format (json, pdf) (default: json)

Response (JSON format)

1{
2  "balanceSheet": {
3    "assets": [
4      {
5        "name": "Cash",
6        "balance": 10500.0
7      },
8      {
9        "name": "Accounts Receivable",
10        "balance": 25000.0
11      }
12      // Additional asset accounts...
13    ],
14    "liabilities": [
15      {
16        "name": "Accounts Payable",
17        "balance": 15000.0
18      }
19      // Additional liability accounts...
20    ],
21    "equity": [
22      {
23        "name": "Owner's Capital",
24        "balance": 50000.0
25      }
26      // Additional equity accounts...
27    ],
28    "totalAssets": 150000.0,
29    "totalLiabilities": 75000.0,
30    "totalEquity": 75000.0
31  },
32  "pdf_urls": {
33    "balance_sheet": "https://storage.openledger.com/reports/bs-123456.pdf"
34  }
35}

Generate a General Ledger Report

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

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

Query Parameters

ParameterTypeDescription
startDatestringStart date (YYYY-MM-DD)
endDatestringEnd date (YYYY-MM-DD)
accountIdsarrayOptional array of account IDs to filter by
formatstringResponse format (json, pdf) (default: json)

Response (JSON format)

1{
2  "accounts": [
3    {
4      "name": "Cash",
5      "type": "ASSET",
6      "financial_type": "CASH",
7      "account_code": 1010,
8      "sub_type_code": 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    }
17    // Additional accounts...
18  ],
19  "entries": [
20    {
21      "id": "entry_123456",
22      "ledger_id": "ldgr_789012",
23      "debit_account_id": "acc_cash",
24      "credit_account_id": "acc_revenue",
25      "amount": 1000.0,
26      "description": "Service payment received",
27      "status": "POSTED",
28      "created_at": "2024-01-15T14:30:00Z"
29    }
30    // Additional entries...
31  ],
32  "pdf_url": "https://storage.openledger.com/reports/gl-123456.pdf"
33}

Report Customization and Filters

You can customize reports with these additional parameters:

ParameterDescription
includeZeroBalancesInclude accounts with zero balances (boolean)
compareWithPreviousInclude comparison with previous period (boolean)
comparisonTypeType of comparison: “month”, “quarter”, “year”
showPercentagesShow percentage changes (boolean)
groupByGroup results by a specific field (e.g., “category”)

Error Handling

Status CodeDescription
400Bad Request - Invalid input parameters
401Unauthorized - Invalid or missing API key
403Forbidden - Insufficient permissions
404Not Found - Report not found
422Unprocessable Entity - Invalid report configuration
429Too Many Requests - Rate limit exceeded
500Internal Server Error

Best Practices

  1. Regular reporting: Generate and save reports at consistent intervals (monthly, quarterly, yearly) for historical comparison.

  2. Export formats: Choose appropriate formats based on your needs:

    • JSON: For programmatic analysis and integration
    • PDF: For presentation and sharing

  3. Date ranges: Use consistent date ranges for comparable reports.

  4. Data quality: Ensure all transactions are properly categorized before generating reports.

  5. Caching: Cache report results when appropriate to improve performance for frequently accessed reports.

Next Steps

Ledger Accounts

Manage chart of accounts

Transactions

Record financial transactions