Fetch all Sub-Entities

This endpoint retrieves a paginated list of all sub-entities (sub-institutions) belonging to the institution associated with the auth token.

GET {{host}}/api/v1/institutions/fetch/sub-entity

Query Parameters

#	Field Name	Data Type	Required	Default	Description
1	`page`	Integer	Yes	1	Page number to retrieve (1-indexed)
2	`perPage`	Integer	Yes	20	Number of records to return per page

Sample Request

GET {{host}}/api/v1/institutions/fetch/sub-entity?page=1&perPage=20

Response Message Field Description

#	Field Name	Description
1	`page`	The current page number returned
2	`perPage`	Number of records per page
3	`message`	Human-readable result message
4	`totalData`	Total number of sub-entity records across all pages
5	`totalFilteredCount`	Total number of records matching any applied filters
6	`data`	Array of sub-entity objects
6.1	`data[].id`	Unique internal identifier of the sub-entity
6.2	`data[].institutionId`	Unique internal ID of the parent institution
6.3	`data[].institutionCode`	Alphanumeric code identifying the parent institution
6.4	`data[].name`	Display name of the sub-entity
6.5	`data[].email`	Contact email address of the sub-entity
6.6	`data[].vaultId`	Vault identifier assigned to the sub-entity
6.7	`data[].kycStatus`	Current KYC verification status of the sub-entity
6.8	`data[].kycLevel`	KYC level of the sub-entity
6.9	`data[].enabled`	Whether the sub-entity is currently active
6.10	`data[].createdOn`	Timestamp of when the sub-entity was created
6.11	`data[].lastUpdatedOn`	Timestamp of the most recent update to the sub-entity record

Sample Response (Success)

{
  "page": 1,
  "perPage": 20,
  "message": "Success",
  "totalData": 45,
  "totalFilteredCount": 45,
  "data": [
    {
      "id": 12,
      "institutionId": 3,
      "institutionCode": "ACME001",
      "name": "Acme Sub-entity Alpha",
      "email": "[email protected]",
      "vaultId": "88",
      "kycStatus": "APPROVED",
      "kycLevel": "TIER_2",
      "enabled": true,
      "createdOn": "2025-12-01T09:00:00",
      "lastUpdatedOn": "2026-02-10T14:30:00"
    }
  ]
}

Sample Response (Failure)

{
  "success": false,
  "responseCode": "401",
  "responseMessage": "Unauthorized"
}