Pools

The Pools module manages organization-level fund pools used as aggregate containers for investments and takaful. Each pool has a pool_type (investment / takaful), currency, total balance, and one optional pool_config that defines ROI rate, ROI cycle, contribution limits, lock-in days, and notice days for withdrawal. A single PoolsController at /pools; pool creation is not exposed here (handled during onboarding/initialization), but pool config can be created and updated.

Property	Value
Base URL	{HOST}/v1
Auth	Bearer JWT (header Authorization) or access_token cookie
Content-Type	application/json
Error envelope	{ "message": string | string[], "statusCode": number, "error": string }
Validation	Global ValidationPipe · whitelist: true, forbidNonWhitelisted: true · unknown fields → 400
Related modules	organizations, accounts, investments, takaful, withdrawal
Document version	v1 · 2026-05-20
Audience	Internal FE devs (mobile + web)

Summary

Organization admins read the list of pools they own and the detail of each pool / its config. Only the MORIA superadmin can create or full-replace a pool config (Put). The pool’s name / status / currency fields can be updated by MORIA and ORGANIZATION. All actions are logged via BusinessEvent.

Method	Path	Auth	Summary
GET	/v1/pools	bearer	List pools for one organization (paginated)
GET	/v1/pools/:pool_id	bearer	Detail of one pool
GET	/v1/pools/config/:pool_id	bearer	Config detail for one pool
POST	/v1/pools/config	bearer	Create pool config (MORIA only)
PUT	/v1/pools/config	bearer	Full-replace pool config (MORIA only)
PATCH	/v1/pools/:pool_id	bearer	Update pool fields (name, currency, status)

Auth + scope notes

• All endpoints require Bearer JWT.
• GET /pools requires the query organization_id (UUID, validated via ParseUUIDPipe) — the server does not auto-resolve from the logged-in user.
• Pool config: create and full-replace via PUT are MORIA-role only. For partial field updates use PATCH (currently not available for config — only for the pool itself).
• PATCH /pools/:pool_id is allowed for both MORIA and ORGANIZATION (org admin) roles.
• All endpoints emit @BusinessEvent — FE telemetry can subscribe to RESOURCE_FETCHED / RESOURCE_CREATED / RESOURCE_UPDATED types.

---

GET /v1/pools bearer

List pools for one organization. The organization_id query is required and must be a UUID. The result is paginated with page, limit, and ordered by created_at (asc/desc).

bearer MORIA, ORGANIZATION read-pool RESOURCE_FETCHED

Query params

Param	Type	Default	Notes
organization_id	string (UUID)	—	Required — validated by ParseUUIDPipe
page	number	1	Page number
limit	number	10	Records per page
order	'asc' | 'desc'	desc	Order by created_at

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Pools retrieved successfully",
  "data": {
    "limit": 10,
    "count": 5,
    "currentPage": 1,
    "totalPages": 1,
    "pools": [
      {
        "id": "be2cb7da-e217-401c-8d07-b01e64adfb34",
        "organization_id": "123e4567-e89b-12d3-a456-426614174000",
        "account_id": "123e4567-e89b-12d3-a456-426614174001",
        "pool_type": "investment",
        "name": "Emergency Fund Pool",
        "total_balance": "25000000.0000",
        "currency": "IDR",
        "status": "active",
        "created_at": "2026-01-10T08:30:00.000Z",
        "updated_at": "2026-05-20T08:30:00.000Z"
      }
    ]
  }
}

Errors

Status	When it occurs
400 Bad Request	organization_id is not a UUID / empty
401 Unauthorized	Bearer/cookie token is invalid
403 Forbidden	Missing read-pool permission or role is not MORIA/ORGANIZATION

---

GET /v1/pools/:pool_id bearer

Detail of one pool. No explicit role gate on the controller — only the read-pool permission and a valid Bearer are needed.

bearer read-pool RESOURCE_FETCHED

Path params

Param	Type	Notes
pool_id	UUID	Validated via ParseUUIDPipe

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Pool retrieved successfully",
  "data": {
    "pool": {
      "id": "be2cb7da-e217-401c-8d07-b01e64adfb34",
      "organization_id": "123e4567-e89b-12d3-a456-426614174000",
      "account_id": "123e4567-e89b-12d3-a456-426614174001",
      "pool_type": "investment",
      "name": "Emergency Fund Pool",
      "total_balance": "25000000.0000",
      "currency": "IDR",
      "status": "active",
      "created_at": "2026-01-10T08:30:00.000Z",
      "updated_at": "2026-05-20T08:30:00.000Z"
    }
  }
}

Errors

Status	When it occurs
400 Bad Request	pool_id is not a UUID
401 Unauthorized	Bearer/cookie token is invalid
403 Forbidden	Missing read-pool permission
404 Not Found	Pool not found

---

GET /v1/pools/config/:pool_id bearer

Detail of one pool’s configuration (ROI rate, ROI cycle, contribution limits, lock-in, notice days). Separate permission: read-pool-config.

bearer read-pool-config RESOURCE_FETCHED

Path params

Param	Type	Notes
pool_id	UUID	Validated via ParseUUIDPipe

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Pool config for pool id be2cb7da-e217-401c-8d07-b01e64adfb34 retrieved successfully",
  "data": {
    "pool_config": {
      "id": "990e8400-e29b-41d4-a716-446655440444",
      "pool_id": "be2cb7da-e217-401c-8d07-b01e64adfb34",
      "roi_rate": "0.0500",
      "roi_cycle": "monthly",
      "min_contribution": "1000.0000",
      "max_contribution": "100000.0000",
      "lock_in_days": 30,
      "min_withdrawal": "500.0000",
      "notice_days": 7,
      "is_active": true,
      "created_at": "2026-01-10T08:30:00.000Z",
      "updated_at": "2026-05-20T08:30:00.000Z"
    }
  }
}

Errors

Status	When it occurs
400 Bad Request	pool_id is not a UUID
401 Unauthorized	Bearer/cookie token is invalid
403 Forbidden	Missing read-pool-config permission
404 Not Found	Pool config not found

---

POST /v1/pools/config bearer

Create a new pool config for a pool. Only the MORIA (superadmin) role can call this endpoint.

bearer MORIA create-pool-config RESOURCE_CREATED

Request body — CreatePoolConfigDto

Field	Type	Required	Notes
pool_id	string (UUID)	yes	ID of the pool to be configured · IsUUID
roi_rate	string (numeric)	optional	ROI rate (e.g. "0.05" = 5%) · IsNumberString
roi_cycle	enum ROICycle	optional	monthly, quarterly, yearly
min_contribution	string (numeric)	optional	Minimum contribution (rupiah, integer/decimal)
max_contribution	string (numeric)	optional	Maximum contribution
lock_in_days	integer	optional	Minimum days funds are locked before withdrawal
min_withdrawal	string (numeric)	optional	Minimum withdrawal amount
notice_days	integer	optional	Notice days required before withdrawal

Example request

{
  "pool_id": "be2cb7da-e217-401c-8d07-b01e64adfb34",
  "roi_rate": "0.05",
  "roi_cycle": "monthly",
  "min_contribution": "1000.00",
  "max_contribution": "100000.00",
  "lock_in_days": 30,
  "min_withdrawal": "500.00",
  "notice_days": 7
}

Response — 201 Created

{
  "status": "success",
  "statusCode": 200,
  "message": "Pool configuration created successfully",
  "data": {
    "pool_config": {
      "id": "990e8400-e29b-41d4-a716-446655440444",
      "pool_id": "be2cb7da-e217-401c-8d07-b01e64adfb34",
      "roi_rate": "0.0500",
      "roi_cycle": "monthly",
      "min_contribution": "1000.0000",
      "max_contribution": "100000.0000",
      "lock_in_days": 30,
      "min_withdrawal": "500.0000",
      "notice_days": 7,
      "is_active": true,
      "created_at": "2026-05-20T08:30:00.000Z"
    }
  }
}

Note: the current controller code sets the statusCode field to 200 even though the HTTP response status is 201 Created (Nest default for @Post()). FE should rely on the HTTP status, not the body statusCode for this endpoint.

Errors

Status	When it occurs
400 Bad Request	pool_id is not a UUID · invalid enum/numeric
401 Unauthorized	Bearer/cookie token is invalid
403 Forbidden	Role is not MORIA or missing create-pool-config permission
404 Not Found	Pool with pool_id not found

Side effects

• Emit BusinessEvent RESOURCE_CREATED (impact MEDIUM, request body captured).

---

PUT /v1/pools/config bearer

Full-replace pool config (every optional field sent will overwrite). MORIA role only.

bearer MORIA update-pool-config RESOURCE_UPDATED

Request body — UpdatePoolConfigDto

Field	Type	Required	Notes
pool_id	string (UUID)	yes	ID of the pool whose config is updated
roi_rate	string (numeric)	optional	New ROI rate
roi_cycle	enum ROICycle	optional	monthly, quarterly, yearly
min_contribution	string (numeric)	optional
max_contribution	string (numeric)	optional
lock_in_days	integer	optional
min_withdrawal	string (numeric)	optional
notice_days	integer	optional

Example request

{
  "pool_id": "be2cb7da-e217-401c-8d07-b01e64adfb34",
  "roi_rate": "0.06",
  "roi_cycle": "quarterly",
  "lock_in_days": 60
}

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Pool configuration updated successfully",
  "data": {
    "pool_config": { "...": "shape matches GET /v1/pools/config/:pool_id" }
  }
}

Errors

Status	When it occurs
400 Bad Request	Invalid body (pool_id not UUID, wrong enum, wrong numeric)
401 Unauthorized	Bearer/cookie token is invalid
403 Forbidden	Role is not MORIA or missing update-pool-config permission
404 Not Found	Pool / pool config not found

Side effects

• Emit BusinessEvent RESOURCE_UPDATED (impact MEDIUM, request body captured).

---

PATCH /v1/pools/:pool_id bearer

Update the pool fields themselves (not the config) — name, currency, status. Callable by both MORIA and ORGANIZATION.

bearer MORIA, ORGANIZATION update-pool RESOURCE_UPDATED

Path params

Param	Type	Notes
pool_id	UUID	Validated via ParseUUIDPipe

Request body — UpdatePoolDto

Field	Type	Required	Notes
name	string	optional	New pool name
currency	string	optional	Currency code (DB default IDR)
status	enum PoolStatus	optional	active, inactive

Example request

{
  "name": "Emergency Fund Pool 2026",
  "status": "active"
}

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Pool information updated successfully",
  "data": {
    "pool": { "...": "shape matches GET /v1/pools/:pool_id" }
  }
}

Errors

Status	When it occurs
400 Bad Request	pool_id is not a UUID · invalid status enum
401 Unauthorized	Bearer/cookie token is invalid
403 Forbidden	Role is not MORIA/ORGANIZATION · missing update-pool permission
404 Not Found	Pool not found

Side effects

• Emit BusinessEvent RESOURCE_UPDATED (impact MEDIUM, request body captured).

---

Reference

Enum: PoolType

• investment — pool for investment products
• takaful — pool for takaful products

Enum: PoolStatus

• active · inactive

Enum: ROICycle

• monthly · quarterly · yearly

Permissions used

• read-pool — list + pool detail
• read-pool-config — config detail
• create-pool-config — create config (MORIA)
• update-pool-config — replace config (MORIA)
• update-pool — update pool (MORIA/ORG)

Standard error envelope

{
  "message": "Validation failed (uuid is expected)",
  "statusCode": 400,
  "error": "Bad Request"
}

message can be a string or an array of strings (multi-field validation error).

Common HTTP codes

• 400 body/query/param validation invalid
• 401 token expired / missing
• 403 wrong role · missing permission
• 404 pool / pool config not found
• 500 internal — show a generic toast

FE notes

• The pool creation endpoint itself (POST /pools) is not exposed in the current controller — pools are created by the backend during onboarding/initialization. FE does not need a create-pool form.
• The total_balance field is always a numeric string (precision 20, scale 4) — render as rupiah with client-side formatting.
• roi_rate is fractional (e.g. 0.0500 = 5%); do not multiply by 100 on display if you are already using a percent helper.