Investment Management System API Documentation

System Summary

Stack: PHP + MySQL. Auth: WhatsApp OTP + JWT (7 days). Roles: admin, agent, investor. Admin login bypasses OTP. No cron/background jobs; due states are computed with query-time rules.

Implementation

ItemValue
Entrypointapi/public/index.php
Main API Classapi/src/App.php
Server Rewriteapi/public/.htaccess routes all API paths to index.php
Auth HeaderAuthorization: Bearer {{access_token}}
Environment VarsDB_HOST DB_PORT DB_NAME DB_USER DB_PASS JWT_SECRET APP_ENV
DB SchemaImport api/database.sql before running APIs.
Test SeedImport api/test_seed.sql for login accounts + dummy test data.
Response FormatJSON for all endpoints. Error format: {"error":"message"}
Admin AuthAdmin user can verify login without OTP via /api/auth/verify-otp using phone.
Direct LoginPOST /api/auth/login with phone + password (bcrypt hash in users.password_hash).

Business Rules

RuleValue
Minimum InvestmentINR 100000
Plan Tenure20 months
Monthly Payout10% total = 5% principal + 5% interest
Lock-in3 months
Early ClosureAfter lock-in, settlement = remaining principal only
Agent Commission5% upfront + 1% monthly for 20 months
Payout CyclesInvested on 1-10 -> 15th next month; 11-20 -> 25th next month; 21-31 -> 5th month-after-next

Database Mapping

Core tables: users, bank_accounts, bank_change_requests, investments, payout_schedule, agent_commissions, otp_verifications, investor_requests, payout_batches, payout_batch_items. API payloads below align to these entities.

Authentication APIs

POST/api/auth/send-otp
Send OTP to WhatsApp for agent/investor login/signup.
curl -X POST https://app.expert-research.in/api/auth/send-otp \
  -H "Content-Type: application/json" \
  -d '{"phone":"919876543210","purpose":"login"}'
POST/api/auth/login
Direct password login for users having users.password_hash.
curl -X POST https://app.expert-research.in/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"phone":"919900000001","password":"Admin@123"}'
POST/api/auth/verify-otp
Verify OTP and issue JWT + refresh token.
curl -X POST https://app.expert-research.in/api/auth/verify-otp \
  -H "Content-Type: application/json" \
  -d '{"phone":"919876543210","otp":"123456"}'
POST/api/auth/refresh-token
Return a new JWT using refresh token.
curl -X POST https://app.expert-research.in/api/auth/refresh-token \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"your_refresh_token"}'

User APIs

GET/api/user/profile
Get current user profile and active bank account details.
curl -X GET https://app.expert-research.in/api/user/profile \
  -H "Authorization: Bearer {{access_token}}"
POST/api/user/update-profile
Update profile fields (name/PAN/Aadhaar).
curl -X POST https://app.expert-research.in/api/user/update-profile \
  -H "Authorization: Bearer {{access_token}}" \
  -H "Content-Type: application/json" \
  -d '{"name":"Amit Shah","pan_number":"ABCDE1234F","aadhaar_number":"123412341234"}'

Investor APIs

GET/api/investor/dashboard
Portfolio summary: active investments, next payout, totals.
curl -X GET https://app.expert-research.in/api/investor/dashboard -H "Authorization: Bearer {{access_token}}"
GET/api/investor/investments
List investor investments with status and maturity/lock-in dates.
curl -X GET https://app.expert-research.in/api/investor/investments -H "Authorization: Bearer {{access_token}}"
GET/api/investor/payouts
List payout history from payout_schedule for investor investments.
curl -X GET https://app.expert-research.in/api/investor/payouts?status=paid -H "Authorization: Bearer {{access_token}}"
POST/api/investor/request-investment
Create investment request; status starts as pending_admin_approval.
curl -X POST https://app.expert-research.in/api/investor/request-investment \
  -H "Authorization: Bearer {{access_token}}" -H "Content-Type: application/json" \
  -d '{"amount":100000,"txn_id":"TXN12345","proof_image":"https://cdn/proof.jpg"}'
POST/api/investor/request-closure
Request early closure after lock-in; creates investor_requests row.
curl -X POST https://app.expert-research.in/api/investor/request-closure \
  -H "Authorization: Bearer {{access_token}}" -H "Content-Type: application/json" \
  -d '{"investment_id":45,"message":"Need funds urgently"}'
POST/api/investor/bank-change-request
Submit bank update request; admin approval required before bank_accounts update.
curl -X POST https://app.expert-research.in/api/investor/bank-change-request \
  -H "Authorization: Bearer {{access_token}}" -H "Content-Type: application/json" \
  -d '{"account_holder":"Rahul Jain","bank_name":"HDFC","account_number":"1234567890","ifsc_code":"HDFC0000123","branch":"Andheri"}'

Agent APIs

GET/api/agent/dashboard
Agent summary: onboarded investors, active investments, commission due.
curl -X GET https://app.expert-research.in/api/agent/dashboard -H "Authorization: Bearer {{access_token}}"
POST/api/agent/investor/create
Create investor under agent referral.
curl -X POST https://app.expert-research.in/api/agent/investor/create \
  -H "Authorization: Bearer {{access_token}}" -H "Content-Type: application/json" \
  -d '{"name":"Priya Singh","phone":"919811112222","pan_number":"ABCDE1234F"}'
GET/api/agent/investors
List investors referred by logged-in agent.
curl -X GET https://app.expert-research.in/api/agent/investors -H "Authorization: Bearer {{access_token}}"
POST/api/agent/investment/create
Create investment request for an investor; pending admin approval.
curl -X POST https://app.expert-research.in/api/agent/investment/create \
  -H "Authorization: Bearer {{access_token}}" -H "Content-Type: application/json" \
  -d '{"investor_id":12,"amount":200000,"txn_id":"TXN9911","proof_image":"https://cdn/inv-proof.jpg"}'
GET/api/agent/commissions
View signup and monthly commissions from agent_commissions.
curl -X GET https://app.expert-research.in/api/agent/commissions?status=pending -H "Authorization: Bearer {{access_token}}"
POST/api/agent/bank-change-request
Submit bank account change request for agent user.
curl -X POST https://app.expert-research.in/api/agent/bank-change-request \
  -H "Authorization: Bearer {{access_token}}" -H "Content-Type: application/json" \
  -d '{"account_holder":"Agent Name","bank_name":"ICICI","account_number":"9988776655","ifsc_code":"ICIC0001234","branch":"Pune"}'

Admin APIs

POST/api/admin/agent/create
Create agent user (admin-only; OTP bypass for admin account management flow).
curl -X POST https://app.expert-research.in/api/admin/agent/create \
  -H "Authorization: Bearer {{access_token}}" -H "Content-Type: application/json" \
  -d '{"name":"New Agent","phone":"919900001111"}'
POST/api/admin/investor/create
Create investor directly from admin panel.
curl -X POST https://app.expert-research.in/api/admin/investor/create \
  -H "Authorization: Bearer {{access_token}}" -H "Content-Type: application/json" \
  -d '{"name":"New Investor","phone":"919900002222"}'
GET/api/admin/investments/pending
List pending investments awaiting payment verification.
curl -X GET https://app.expert-research.in/api/admin/investments/pending -H "Authorization: Bearer {{access_token}}"
POST/api/admin/investment/approve
Approve investment, activate it, compute first payout date, create 20 payouts and commission rows.
curl -X POST https://app.expert-research.in/api/admin/investment/approve \
  -H "Authorization: Bearer {{access_token}}" -H "Content-Type: application/json" \
  -d '{"investment_id":45}'
POST/api/admin/investment/reject
Reject a pending investment request.
curl -X POST https://app.expert-research.in/api/admin/investment/reject \
  -H "Authorization: Bearer {{access_token}}" -H "Content-Type: application/json" \
  -d '{"investment_id":45,"reason":"Payment proof mismatch"}'
POST/api/admin/closure/approve
Approve early closure request and lock investment for settlement scheduling.
curl -X POST https://app.expert-research.in/api/admin/closure/approve \
  -H "Authorization: Bearer {{access_token}}" -H "Content-Type: application/json" \
  -d '{"request_id":77}'
POST/api/admin/closure/reject
Reject early closure request.
curl -X POST https://app.expert-research.in/api/admin/closure/reject \
  -H "Authorization: Bearer {{access_token}}" -H "Content-Type: application/json" \
  -d '{"request_id":77,"reason":"Lock-in not completed"}'
POST/api/admin/closure/schedule-settlement
Schedule settlement payout entry (type settlement) for remaining principal.
curl -X POST https://app.expert-research.in/api/admin/closure/schedule-settlement \
  -H "Authorization: Bearer {{access_token}}" -H "Content-Type: application/json" \
  -d '{"investment_id":45,"settlement_amount":70000,"payout_date":"2026-04-25"}'
POST/api/admin/bank-change/approve
Approve bank change request and update active bank account.
curl -X POST https://app.expert-research.in/api/admin/bank-change/approve \
  -H "Authorization: Bearer {{access_token}}" -H "Content-Type: application/json" \
  -d '{"request_id":31}'
POST/api/admin/bank-change/reject
Reject bank change request.
curl -X POST https://app.expert-research.in/api/admin/bank-change/reject \
  -H "Authorization: Bearer {{access_token}}" -H "Content-Type: application/json" \
  -d '{"request_id":31,"reason":"Invalid IFSC"}'

Payout APIs

GET/api/payouts/due
Return pending payouts where payout_date <= today.
curl -X GET https://app.expert-research.in/api/payouts/due -H "Authorization: Bearer {{access_token}}"
POST/api/payouts/generate-batch
Generate payout batch and CSV data fields: account_number, ifsc, account_holder, amount, remarks.
curl -X POST https://app.expert-research.in/api/payouts/generate-batch \
  -H "Authorization: Bearer {{access_token}}" -H "Content-Type: application/json" \
  -d '{"payout_date":"2026-03-25"}'
POST/api/payouts/mark-paid
Mark payout items paid; if 20th regular payout is paid, investment becomes completed.
curl -X POST https://app.expert-research.in/api/payouts/mark-paid \
  -H "Authorization: Bearer {{access_token}}" -H "Content-Type: application/json" \
  -d '{"payout_ids":[101,102,103],"paid_at":"2026-03-25T12:30:00"}'
GET/api/payouts/history
Historical payouts with filters by date, status, investor, investment.
curl -X GET "https://app.expert-research.in/api/payouts/history?from=2026-01-01&to=2026-03-31" \
  -H "Authorization: Bearer {{access_token}}"

Commission APIs

GET/api/commissions/due
Pending commissions due for payout (upfront + monthly).
curl -X GET https://app.expert-research.in/api/commissions/due -H "Authorization: Bearer {{access_token}}"
POST/api/commissions/generate-batch
Prepare a payable commission batch export.
curl -X POST https://app.expert-research.in/api/commissions/generate-batch \
  -H "Authorization: Bearer {{access_token}}" -H "Content-Type: application/json" \
  -d '{"cycle_month":"2026-03"}'
POST/api/commissions/mark-paid
Mark commission records paid and trigger notification flow.
curl -X POST https://app.expert-research.in/api/commissions/mark-paid \
  -H "Authorization: Bearer {{access_token}}" -H "Content-Type: application/json" \
  -d '{"commission_ids":[221,222],"paid_at":"2026-03-25T14:00:00"}'
GET/api/commissions/history
Commission payment history with status/date filters.
curl -X GET "https://app.expert-research.in/api/commissions/history?status=paid" \
  -H "Authorization: Bearer {{access_token}}"

Report APIs

GET/api/reports/investments
Investment report by status/date/agent/investor.
curl -X GET "https://app.expert-research.in/api/reports/investments?status=active" \
  -H "Authorization: Bearer {{access_token}}"
GET/api/reports/payouts
Payout summary and detail report.
curl -X GET "https://app.expert-research.in/api/reports/payouts?from=2026-01-01&to=2026-03-01" \
  -H "Authorization: Bearer {{access_token}}"
GET/api/reports/commissions
Commission report by agent and payout state.
curl -X GET "https://app.expert-research.in/api/reports/commissions?agent_id=5" \
  -H "Authorization: Bearer {{access_token}}"
GET/api/reports/agents
Agent performance report (investor count, AUM, commissions).
curl -X GET https://app.expert-research.in/api/reports/agents \
  -H "Authorization: Bearer {{access_token}}"