Update Sub-Entity

This endpoint updates the details of an existing sub-entity (e.g. a branch or zone) that belongs to the institution associated with the token. The sub-entity to be updated is identified by the {{id}} path parameter.

PATCH {{host}}/api/v1/institutions/update/sub-entity/{{id}}

Content-Type: application/json

Request Message Description

#	Field Name	Data Type	Max Length (API)	Max Length (UI)	Required	Description
1	`name`	String	-	-	No	Updated name for the sub-entity
2	`email`	String	-	-	No	Updated contact email address for the sub-entity
3	`enabled`	Boolean	-	-	No	Enable or disable the sub-entity (`true`/`false`)
4	`additionalInfo`	Object	-	-	No	Optional object for updated metadata
4.1	`additionalInfo.description`	String	-	-	No	Updated description of the sub-entity
4.2	`additionalInfo.address`	String	-	-	No	Updated physical address of the sub-entity
4.3	`additionalInfo.controller`	String	-	-	No	Controller direction or reference for the sub-entity

Sample Request

{
  "name": "Yab Zone T1"
}

Response Message Field Description

#	Field Name	Description
1	`success`	Indicates whether the request was successful (`true` for success)
2	`responseCode`	HTTP-like response code (e.g. `200` for success)
3	`responseMessage`	Human-readable result message (e.g. `Success`)
4	`data`	Object containing the updated sub-entity details
4.1	`data.id`	Unique internal ID of the sub-entity
4.2	`data.createdOn`	Timestamp when the sub-entity was originally created (ISO 8601)
4.3	`data.lastUpdatedOn`	Timestamp of the most recent update to the sub-entity (ISO 8601)
4.4	`data.institutionId`	Internal ID of the parent institution this sub-entity belongs to
4.5	`data.institutionCode`	Short unique code of the parent institution
4.6	`data.name`	Updated name of the sub-entity
4.7	`data.vaultId`	Vault identifier associated with the sub-entity
4.8	`data.kycStatus`	KYC verification status of the sub-entity (e.g. `DISABLED`)
4.9	`data.kycLevel`	KYC tier level assigned to the sub-entity (e.g. `TIER_1`)
4.10	`data.enabled`	Indicates whether the sub-entity is currently active (`true`/`false`)
4.11	`data.additionalInfo`	JSON string containing extra metadata (e.g. description and address)

Sample Response (Success)

{
  "success": true,
  "responseCode": "200",
  "responseMessage": "Success",
  "data": {
    "id": 77,
    "createdOn": "2026-05-20T21:04:59.7633333",
    "lastUpdatedOn": "2026-05-20T21:04:59.7633333",
    "institutionId": 2,
    "institutionCode": "HYDR",
    "name": "Yab Zone T1",
    "vaultId": "94",
    "kycStatus": "DISABLED",
    "kycLevel": "TIER_1",
    "enabled": true,
    "additionalInfo": "{\"description\":\"yaba branch custom wallet\",\"address\":\"Sabo Yaba\"}"
  }
}

Sample Response (Failure)

{
  "success": false,
  "responseCode": "400",
  "responseMessage": "Entity Name You're Trying to Update Already Exists Within Your Domain"
}