Accounts API

Manage the chart of accounts and chartered accounts for an organization — create, list, update, delete, and query dropdown data.

Authentication

All endpoints require a valid Bearer token in the Authorization header.

Endpoints

Accounts

Method	Path	Description
GET	/api/account/:orgId/list	List all accounts
GET	/api/account/:orgId/overview	Get account overview stats
POST	/api/account/:orgId/create	Create a new account
PUT	/api/account/:orgId/:id/update	Update an account
GET	/api/account/:orgId/:parentId/children	Get child accounts of a parent
DELETE	/api/account/:orgId/:id/delete	Delete an account
POST	/api/account/:orgId/dropdown	Get accounts by dropdown type

Chartered Accounts

Method	Path	Description
GET	/api/chartered-account/:orgId/:accountId	Get a single chartered account

Path Parameters

Parameter	Type	Description
orgId	string	Organization ID
id	string	Account document ID
parentId	string	Parent account ID (for tree queries)
accountId	string	Chartered account document ID

---

List Accounts

GET /api/account/:orgId/list

Query Parameters

Parameter	Type	Default	Description
page	number	1	Page number
limit	number	10	Results per page
search	string	—	Search by account name or code
type	string	—	Filter by type (asset, liability, income, expense, equity)

Success Response 200

{
  "success": true,
  "data": [
    {
      "_id": "64f1b2c3d4e5f6a7b8c9d0c1",
      "name": "Cash",
      "type": "asset",
      "code": "1001",
      "parentId": null,
      "isActive": true,
      "balance": 250000,
      "createdAt": "2026-01-01T00:00:00.000Z"
    },
    {
      "_id": "64f1b2c3d4e5f6a7b8c9d0c2",
      "name": "Room Revenue",
      "type": "income",
      "code": "4001",
      "parentId": null,
      "isActive": true,
      "balance": 1500000,
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 42,
    "page": 1,
    "limit": 10,
    "totalPages": 5
  }
}

---

Account Overview

GET /api/account/:orgId/overview

Returns summary statistics for the chart of accounts.

Success Response 200

{
  "success": true,
  "data": {
    "totalAccounts": 42,
    "activeAccounts": 38,
    "inactiveAccounts": 4,
    "byType": [
      { "type": "asset", "count": 12 },
      { "type": "liability", "count": 8 },
      { "type": "income", "count": 10 },
      { "type": "expense", "count": 9 },
      { "type": "equity", "count": 3 }
    ]
  }
}

---

Create Account

POST /api/account/:orgId/create

Request Body

{
  "name": "Petty Cash",
  "type": "asset",
  "code": "1002",
  "parentId": "64f1b2c3d4e5f6a7b8c9d0c1",
  "description": "Small cash expenses account"
}

Field	Type	Required	Description
name	string	Yes	Account display name
type	string	Yes	asset, liability, income, expense, or equity
code	string	Yes	Unique account code
parentId	string	No	Parent account ID for hierarchical chart
description	string	No	Optional description

Success Response 201

{
  "success": true,
  "message": "Account created successfully",
  "data": {
    "_id": "64f1b2c3d4e5f6a7b8c9d0c3",
    "name": "Petty Cash",
    "type": "asset",
    "code": "1002",
    "parentId": "64f1b2c3d4e5f6a7b8c9d0c1",
    "description": "Small cash expenses account",
    "isActive": true,
    "balance": 0,
    "orgId": "64f1b2c3d4e5f6a7b8c9d0e0",
    "createdAt": "2026-02-20T10:00:00.000Z",
    "updatedAt": "2026-02-20T10:00:00.000Z"
  }
}

Error Response 400

{
  "success": false,
  "message": "Validation error",
  "errors": [
    "name is required",
    "code must be unique",
    "type must be one of: asset, liability, income, expense, equity"
  ]
}

Error Response 409

{
  "success": false,
  "message": "Account with code '1002' already exists"
}

---

Update Account

PUT /api/account/:orgId/:id/update

Request Body

{
  "name": "Petty Cash (Main)",
  "description": "Primary petty cash account for daily operations",
  "isActive": true
}

Success Response 200

{
  "success": true,
  "message": "Account updated successfully",
  "data": {
    "_id": "64f1b2c3d4e5f6a7b8c9d0c3",
    "name": "Petty Cash (Main)",
    "type": "asset",
    "code": "1002",
    "description": "Primary petty cash account for daily operations",
    "isActive": true,
    "updatedAt": "2026-02-21T09:00:00.000Z"
  }
}

Error Response 404

{
  "success": false,
  "message": "Account not found"
}

---

Get Child Accounts

GET /api/account/:orgId/:parentId/children

Returns all accounts whose parentId matches the given parent.

Success Response 200

{
  "success": true,
  "data": [
    {
      "_id": "64f1b2c3d4e5f6a7b8c9d0c3",
      "name": "Petty Cash",
      "type": "asset",
      "code": "1002",
      "parentId": "64f1b2c3d4e5f6a7b8c9d0c1",
      "isActive": true,
      "balance": 15000
    },
    {
      "_id": "64f1b2c3d4e5f6a7b8c9d0c4",
      "name": "Bank — HDFC",
      "type": "asset",
      "code": "1003",
      "parentId": "64f1b2c3d4e5f6a7b8c9d0c1",
      "isActive": true,
      "balance": 235000
    }
  ]
}

Error Response 404

{
  "success": false,
  "message": "Parent account not found"
}

---

Delete Account

DELETE /api/account/:orgId/:id/delete

Success Response 200

{
  "success": true,
  "message": "Account deleted successfully"
}

Error Response 404

{
  "success": false,
  "message": "Account not found"
}

Error Response 409

{
  "success": false,
  "message": "Cannot delete account with existing transactions or child accounts"
}

---

Get Accounts by Dropdown Type

POST /api/account/:orgId/dropdown

Returns accounts filtered by a specific dropdown type, useful for populating form selects.

Request Body

{
  "dropdownType": "paid_through"
}

Field	Type	Required	Description
dropdownType	string	Yes	Dropdown category — e.g. paid_through, deposit_to, expense_account

Success Response 200

{
  "success": true,
  "data": [
    {
      "_id": "64f1b2c3d4e5f6a7b8c9d0c1",
      "name": "Cash",
      "code": "1001",
      "type": "asset"
    },
    {
      "_id": "64f1b2c3d4e5f6a7b8c9d0c3",
      "name": "Petty Cash",
      "code": "1002",
      "type": "asset"
    },
    {
      "_id": "64f1b2c3d4e5f6a7b8c9d0c4",
      "name": "Bank — HDFC",
      "code": "1003",
      "type": "asset"
    }
  ]
}

Error Response 400

{
  "success": false,
  "message": "Invalid dropdown type"
}

---

Get Chartered Account

GET /api/chartered-account/:orgId/:accountId

Retrieve a single chartered (standard/template) account by its ID.

Success Response 200

{
  "success": true,
  "data": {
    "_id": "64f1b2c3d4e5f6a7b8c9d0d1",
    "name": "Accounts Receivable",
    "type": "asset",
    "code": "1100",
    "description": "Amounts owed to the organization by customers",
    "parentId": null,
    "isSystemAccount": true,
    "orgId": "64f1b2c3d4e5f6a7b8c9d0e0",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  }
}

Error Response 404

{
  "success": false,
  "message": "Chartered account not found"
}