Account Types API

Manage the ledger account types used to categorize payments. All endpoints are under the base path:

/api/accountTypes

Auth: Cookie-based JWT. Roles and access are enforced via authorize(...) middleware.

---

Authorization Matrix

Endpoint	Method	Roles
/api/accountTypes	GET	admin, agent, finance
/api/accountTypes	POST	admin
/api/accountTypes/:id	PUT	admin
/api/accountTypes/:id	DELETE	admin

---

Data Model

AccountType

{
  "id": number,
  "name": string,
  "description": string | null,
  "isActive": boolean,
  "createdBy": string,            // creator user name
  "createdAt": string,            // ISO datetime
  "company": string               // company name
}

Internal columns also include company (numeric id) and createdBy (numeric id). The GET endpoint returns joined display fields shown above.

---

GET /api/accountTypes

Return all account types visible to the requester, with optional filters.

Query Parameters

Name	Type	Description
query	string	Full/partial match on name.
company	number	Filter by company id. If omitted and caller is not super-admin, results are limited to the caller's allowed companies.
showDisabled	boolean-like	If provided (any value), include inactive rows; otherwise defaults to only active (isActive = true).

Responses

• 200 OK — Array of AccountType objects
• 401/403 — Unauthorized/Forbidden (missing or insufficient role)
• 500 — Server error

Example

curl -X GET 'https://<host>/api/accountTypes?query=bank&company=3' \
  -H 'Cookie: token=<jwt>'

[
  {
    "id": 12,
    "name": "Bank",
    "description": "Primary operating account",
    "isActive": true,
    "createdBy": "Alice Admin",
    "createdAt": "2025-02-01T08:12:30.000Z",
    "company": "Acme Holdings"
  }
]

---

POST /api/accountTypes

Create a new account type. Admin only.

Request Body

{
  "name": "string",            // required, unique per company
  "description": "string",     // optional
  "company": 3                  // required company id
}

Responses

• 201 Created

{ "message": "AccountTypes created successfully" }

• 400 — Validation or access level errors
• 401/403 — Unauthorized/Forbidden
• 500 — Server error

Example

curl -X POST 'https://<host>/api/accountTypes' \
  -H 'Content-Type: application/json' \
  -H 'Cookie: token=<jwt>' \
  -d '{
        "name": "Credit Card",
        "description": "Corporate card expenses",
        "company": 3
      }'

---

PUT /api/accountTypes/:id

Update an account type by id. Admin only.

Path Params

• id — numeric id of the account type

Request Body

Provide any of the following fields (partial updates supported):

{
  "name": "string",
  "description": "string",
  "isActive": true
}

Side Effects & Notes

• After updating, the service propagates the new name to existing payments rows where payments.accountType matches the old name and payments.company matches the account type's company. This keeps historical payments aligned with renamed account types.

Responses

• 200 OK

{ "message": "AccountTypes updated successfully" }

• 404 — Account type not found
• 401/403 — Unauthorized/Forbidden
• 500 — Server error

Example

curl -X PUT 'https://<host>/api/accountTypes/12' \
  -H 'Content-Type: application/json' \
  -H 'Cookie: token=<jwt>' \
  -d '{ "name": "Operating Bank", "isActive": true }'

---

DELETE /api/accountTypes/:id

Delete an account type by id. Admin only.

This performs a hard delete on the account type row.

Path Params

• id — numeric id of the account type

Responses

• 200 OK

{ "message": "AccountTypes deleted successfully" }

• 401/403 — Unauthorized/Forbidden
• 500 — Server error

Example

curl -X DELETE 'https://<host>/api/accountTypes/12' \
  -H 'Cookie: token=<jwt>'

---

Error Model

Errors are returned as:

{ "message": "string" }

Common statuses:

• 400 Bad Request — invalid id/body, incorrect access level, etc.
• 401 Unauthorized — missing/invalid session token
• 403 Forbidden — authenticated but lacks required role/company access
• 404 Not Found — resource not found
• 500 Server Error — unexpected failure

---

Security & Access Notes

• All routes require a valid session cookie (token) with a JWT signed by the server.
• When company filter is omitted on GET, non–super-admin users are automatically restricted to their allowed companies.
• showDisabled is opt-in; omit it to get only active records.

---

Changelog

• v1.0 — Initial documentation covering list/create/update/delete for Account Types.