API v1 Reference

RESTful API for accessing accounting data. All endpoints require authentication via API key.

Authentication

API Key Authentication

Include your API key in the Authorization header with the Bearer scheme.

Example Header

Authorization: Bearer <your-api-key>

Error Response (401)

{
  "error": "Unauthorized"
}

Note: Generate your API key from your Profile Settings page.

Chart of Accounts

GET

/api/v1/coa

Retrieve the chart of accounts hierarchy.

Query Parameters

Name	Type	Required	Description
active	boolean	Optional	Filter by active status (default: true). Use `all=true` to include inactive.
all	boolean	Optional	Include inactive COA entries.
search	string	Optional	Search by name or code (regex).

Response

[
  {
    "_id": "...",
    "parent": null,
    "code": "1",
    "name": "Current Assets",
    "position": "Db",
    "category": "Asset",
    "isActive": true
  }
]

Accounts

GET

/api/v1/accounts

Retrieve accounts. Optionally filter by COA or get a single account by ID.

Query Parameters

Name	Type	Required	Description
id	string	Optional	Get a single account by ID.
coa	string	Optional	Filter accounts by parent COA ID.
all	boolean	Optional	Include inactive accounts.

Response

[
  {
    "_id": "...",
    "coa": "...",
    "number": "10101",
    "name": "Petty Cash",
    "balance": 5000000,
    "isActive": true
  }
]

Transactions

GET

/api/v1/transactions

List transactions with optional filters.

Query Parameters

Name	Type	Required	Description
id	string	Optional	Get a single transaction by ID.
status	string	Optional	Filter by status: Pending, Confirmed, Rejected, Reversed.
includeDetails	boolean	Optional	Include journal line details.

Response

[
  {
    "_id": "...",
    "code": "GJ-20260701-001",
    "effectiveDate": "2026-07-01T00:00:00.000Z",
    "amount": 1000000,
    "status": "Confirmed",
    "reference": "INV-001",
    "information": "Payment received",
    "source": "api"
  }
]

GET

/api/v1/transactions/:id

Get a single transaction by ID with journal line details.

Response

{
  "_id": "...",
  "code": "GJ-20260701-001",
  "effectiveDate": "2026-07-01T00:00:00.000Z",
  "amount": 1000000,
  "status": "Confirmed",
  "source": "api",
  "details": [
    { "account": { "number": "10101", "name": "Petty Cash" }, "debit": 1000000, "credit": 0 },
    { "account": { "number": "40101", "name": "Revenue" }, "debit": 0, "credit": 1000000 }
  ]
}

POST

/api/v1/transactions

Create a new transaction. At least 2 journal lines required; debits must equal credits.

Request Body

{
  "type": "General",
  "effectiveDate": "2026-07-01",
  "reference": "INV-001",
  "information": "Payment received",
  "lines": [
    { "accountId": "...", "debit": 1000000, "credit": 0 },
    { "accountId": "...", "debit": 0, "credit": 1000000 }
  ]
}

Response

{
  "_id": "...",
  "code": "GJ-20260701-001",
  "status": "Pending",
  "source": "api"
}

PUT

/api/v1/transactions/:id

Update a pending transaction. Replaces all journal lines if provided.

Query Parameters

Name	Type	Required	Description
id	string	Required	Transaction ID (in path).

Request Body

{
  "effectiveDate": "2026-07-02",
  "reference": "INV-001",
  "information": "Updated info",
  "lines": [
    { "accountId": "...", "debit": 2000000, "credit": 0 },
    { "accountId": "...", "debit": 0, "credit": 2000000 }
  ]
}

Response

{
  "message": "Updated."
}

DELETE

/api/v1/transactions/:id?action=confirm

Confirm a pending transaction. Affects account balances.

Response

{
  "message": "Confirmed."
}

DELETE

/api/v1/transactions/:id?action=reject

Reject a pending transaction.

Response

{
  "message": "Rejected."
}

DELETE

/api/v1/transactions/:id?action=cancel

Hard-delete a pending transaction (removes from database).

Response

{
  "message": "Deleted."
}

Transaction Types

GET

/api/v1/transaction-types

List available transaction types and their code prefixes.

Response

{
  "General": "GJ",
  "FundTransfer": "FT",
  "Expense": "EX",
  "Revenue": "RV",
  "Purchase": "PC",
  "Sales": "SL",
  "Payroll": "PR",
  "Tax": "TX",
  "Depreciation": "DP",
  "Closing": "CE"
}

Ledger

GET

/api/v1/ledger-periods

Retrieve ledger entries for a specific account within a date range. Returns opening balance, period mutations, and running balance.

Query Parameters

Name	Type	Required	Description
accountId	string	Required	Account ID to retrieve ledger for.
startDate	string (YYYY-MM-DD)	Optional	Start date (inclusive). Defaults to beginning of current year.
endDate	string (YYYY-MM-DD)	Optional	End date (inclusive). Defaults to today.

Response

{
  "account": { "number": "10101", "name": "Petty Cash" },
  "coa": { "code": "1", "name": "Current Assets", "position": "Db" },
  "openingBalance": 0,
  "startDate": "2026-01-01",
  "endDate": "2026-07-01",
  "rows": [
    { "date": "2026-07-01T00:00:00.000Z", "code": "GJ-20260701-001", "information": "Payment", "debit": 1000000, "credit": 0, "balance": 1000000 }
  ]
}

Reports

GET

/api/v1/reports/balance-sheet

Generate the balance sheet as of a specific date.

Query Parameters

Name	Type	Required	Description
date	string (YYYY-MM-DD)	Optional	Date as of which to generate the balance sheet. Defaults to today.

Response

{
  "asOfDate": "2026-07-01",
  "assets": { "total": 50000000, "children": [...] },
  "liabilities": { "total": 10000000, "children": [...] },
  "equity": { "total": 40000000, "children": [...] },
  "netIncome": 5000000
}

GET

/api/v1/reports/income-statement

Generate the income statement for a date range.

Query Parameters

Name	Type	Required	Description
startDate	string (YYYY-MM-DD)	Optional	Start date (inclusive). Defaults to Jan 1 of current year.
endDate	string (YYYY-MM-DD)	Optional	End date (inclusive). Defaults to today.

Response

{
  "startDate": "2026-01-01",
  "endDate": "2026-07-01",
  "revenue": { "total": 50000000, "children": [...] },
  "cogs": { "total": 20000000, "children": [...] },
  "expenses": { "total": 25000000, "children": [...] },
  "grossProfit": 30000000,
  "netProfit": 5000000
}

Error Codes

400Bad RequestMissing or invalid request parameters / body.

401UnauthorizedMissing or invalid API key.

403ForbiddenAPI key does not have permission for this resource.

404Not FoundThe requested resource does not exist.

409ConflictConflict (e.g., duplicate transaction code, unbalanced journal).

422UnprocessableValidation error (e.g., debits != credits).

Best Practices

Store securely: Treat your API key like a password. Do not expose it in client-side code or version control.

Regenerate periodically: You can regenerate your API key from your profile page at any time. Regenerating invalidates the previous key immediately.

Date format: All dates should be in ISO 8601 format (YYYY-MM-DD) or ISO string (YYYY-MM-DDTHH:mm:ss.sssZ).

Transaction source: Transactions created via the API are automatically marked with source: "api" to distinguish them from UI-created transactions.