📡 Complete API Reference

This document contains the complete list of all REST API endpoints in the platform.

Authentication

Routes: /auth/* — Admin dashboard authentication with TFA support.

Method	Endpoint	Description	Auth
GET	/auth/login-settings	Get login page customization (public)	❌
POST	/auth/login	Admin login (username + password)	❌
POST	/auth/login/2fa	Verify TFA code after login	❌
POST	/auth/logout	Logout and invalidate session	✅
GET	/auth/me	Get current user info + permissions	✅
POST	/auth/tfa/setup	Generate TFA secret + QR code	✅
POST	/auth/tfa/verify	Verify and enable TFA	✅
POST	/auth/tfa/disable	Disable TFA for account	✅

Customers

Routes: /customers/* — Customer CRUD, validation, import, and interest calculations.

Utility Routes

Method	Endpoint	Description	Permission
GET	/customers/last-code	Get next customer code	customers:create
GET	/customers/check-code/:code	Check if customer code is unique	customers:create
GET	/customers/check-pan/:pan	Check if PAN is unique	customers:create
GET	/customers/check-aadhar/:aadhar	Check if Aadhar is unique	customers:create

CRUD Operations

Method	Endpoint	Description	Permission
POST	/customers	Create new customer	customers:create
GET	/customers	List customers (paginated, filterable)	customers:view
GET	/customers/:id	Get single customer details	customers:view
PUT	/customers/:id	Update customer	customers:update
DELETE	/customers/:id	Delete customer	customers:delete
GET	/customers/export	Export customers to CSV/Excel	customers:export

Investment Aggregation & Interest

Method	Endpoint	Description	Permission
GET	/customers/fields/config	Get available fields for selection	customers:view
POST	/customers/aggregate	Aggregate investments with dynamic fields	customers:view
GET	/customers/ncd-summary	Get NCD summary statistics	customers:view
POST	/customers/calculate-interest	Calculate interest for multiple customers	ncd-interest:calculate
GET	/customers/:id/interest	Calculate interest for single customer	ncd-interest:calculate
POST	/customers/export-interest	Export interest data to Excel	ncd-interest:export

Customer Import

Method	Endpoint	Description	Permission
GET	/customers/import/schema	Get import schema for column mapping	customers:import
GET	/customers/import/template	Download Excel import template	customers:import
POST	/customers/import/preview	Preview import with validation	customers:import
POST	/customers/import/execute	Execute batch import	customers:import

NCD Series

Routes: /admin/ncd-series/* — Manage NCD investment series.

Method	Endpoint	Description	Permission
GET	/admin/ncd-series	Get all NCD series	ncd-series:view
GET	/admin/ncd-series/active	Get only active series	ncd-series:view
GET	/admin/ncd-series/:id	Get series by ID	ncd-series:view
GET	/admin/ncd-series/:id/details	Get series with analytics + customers	ncd-series:view
POST	/admin/ncd-series	Create new NCD series	ncd-series:create
PUT	/admin/ncd-series/:id	Update NCD series	ncd-series:update
DELETE	/admin/ncd-series/:id	Delete NCD series (soft)	ncd-series:delete

NCD Operations

Allotment

Method	Endpoint	Description	Permission
GET	/admin/allotment/customers/:seriesId	Get customers eligible for allotment	ncd-allotment:view
POST	/admin/allotment/confirm	Confirm allotment	ncd-allotment:confirm

Transfer

Method	Endpoint	Description	Permission
GET	/admin/transfer/search	Search customers for transfer	ncd-transfer:view
GET	/admin/transfer/customer/:id/investments	Get customer investments	ncd-transfer:view
POST	/admin/transfer/execute	Execute transfer	ncd-transfer:execute

Redemption

Method	Endpoint	Description	Permission
GET	/admin/redemption/eligible-customers/:seriesId	Get eligible customers	ncd-redemption:view
POST	/admin/redemption/request	Create redemption request	ncd-redemption:create
POST	/admin/redemption/approve/:requestId	Approve redemption	ncd-redemption:approve
POST	/admin/redemption/reject/:requestId	Reject redemption	ncd-redemption:approve

Rollover

Method	Endpoint	Description	Permission
GET	/admin/rollover/expired-series	Get expired series	ncd-rollover:view
GET	/admin/rollover/active-series	Get destination options	ncd-rollover:view
POST	/admin/rollover/request	Create rollover request	ncd-rollover:create
POST	/admin/rollover/approve/:requestId	Approve rollover	ncd-rollover:approve

Approvals System

The approval system implements a maker-checker workflow for financial operations. All sensitive operations go through an approval queue before execution.

Approval Workflow Overview

Request Types

Type	Collection Key	Source	Description
allotment	allotment_requests	Dashboard	New investment allotment
redemption	redemption_requests	Dashboard / Mobile	Early exit from investment
transfer	transfer_requests	Dashboard / Mobile	Investment ownership transfer
rollover	rollover_requests	Dashboard	Reinvest matured investment
profile_change	customer_requests	Mobile	Customer profile update
document_update	customer_requests	Mobile	KYC document upload

Request Status Flow

Status	Description	Next Actions
pending	Awaiting approval	approve, reject, send_back
sent_back	Returned for corrections	resubmit, cancel
approved	Approved and executed	None (final)
rejected	Rejected with reason	None (final)
cancelled	Cancelled by creator	None (final)

API Endpoints

Method	Endpoint	Description	Permission
GET	/admin/approvals/counts	Get pending counts by type	approvals:view
GET	/admin/approvals/pending	Get all pending requests (paginated)	approvals:view
GET	/admin/approvals/pending-for-edit	Get requests sent back for editing	approvals:view
GET	/admin/approvals/history	Get approved/rejected history	approvals:view
GET	/admin/approvals/:type/:id	Get single request details	approvals:view
POST	/admin/approvals/:type/:id/approve	Approve request	Varies by type
POST	/admin/approvals/:type/:id/reject	Reject request (requires reason)	Varies by type
POST	/admin/approvals/:type/:id/send-back	Return for corrections (requires note)	Varies by type

Permissions by Request Type

Request Type	Approve Permission	Reject Permission
Allotment	ncd-allotment:confirm	ncd-allotment:confirm
Redemption	ncd-redemption:approve	ncd-redemption:approve
Transfer	ncd-transfer:execute	ncd-transfer:execute
Rollover	ncd-rollover:approve	ncd-rollover:reject
Profile Change	ncd-redemption:approve	ncd-redemption:approve

Request Payload Examples

Approve Request

POST /admin/approvals/redemption/64f123abc/approve
{
  "note": "Approved as per customer request"
}

Reject Request

POST /admin/approvals/redemption/64f123abc/reject
{
  "reason": "Lock-in period not complete. Please try after 01/03/2024"
}

Send Back Request

POST /admin/approvals/profile_change/64f123abc/send-back
{
  "note": "Bank account statement is unclear. Please upload a clearer image."
}

Implementation Notes

• Maker-checker: Users cannot approve their own requests
• Notifications are sent automatically on status change
• All actions are logged in audit trail
• Partial approval supported for bulk allotment requests

Mobile App API

Routes: /mobile/* — Customer mobile app endpoints.

Public Routes

Method	Endpoint	Description
GET	/mobile/app-config	Get app configuration
POST	/mobile/auth/send-otp	Send login OTP
POST	/mobile/auth/verify-otp	Verify OTP
POST	/mobile/register/send-otp	Registration OTP

Protected Routes

Method	Endpoint	Description
GET	/mobile/profile	Get profile
GET	/mobile/summary	Portfolio summary
GET	/mobile/investments	Get investments
GET	/mobile/statements/folios	Get folios list
GET	/mobile/chat/messages	Get messages
GET	/mobile/notifications	Get notifications

Common Error Codes

Code	Meaning
200	Success
201	Created
400	Bad Request / Validation Error
401	Unauthorized / Invalid Token
403	Forbidden / Missing Permission
404	Not Found
409	Conflict (duplicate entry)
500	Internal Server Error