Create Sub-Entity

This endpoint creates a sub-entity (e.g. a branch or zone) under an existing institution.

POST {{url}}/api/v1/institutions/create/sub-entity

Content-Type: application/json

Request Message Description

#	Field Name	Data Type	Required	Description
1	`name`	String	Yes	Name of the sub-entity (e.g. a branch or zone name)
2	`email`	String	Yes	Contact email address for the sub-entity
3	`additionalInfo`	Object	No	Optional key-value pairs for extra metadata about the sub-entity
3.1	`additionalInfo.description`	String	No	A brief description of the sub-entity
3.2	`additionalInfo.address`	String	No	Physical address of the sub-entity

Sample Request

{
  "name": "Yaba Zone 9",
  "email": "[email protected]",
  "additionalInfo": {
    "description": "yaba branch custom wallet",
    "address": "Sabo Yaba"
  }
}

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 newly created sub-entity details
4.1	`data.id`	Unique internal ID assigned to the sub-entity
4.2	`data.createdOn`	Timestamp when the sub-entity was created (ISO 8601)
4.3	`data.institutionId`	Internal ID of the parent institution this sub-entity belongs to
4.4	`data.institutionCode`	Short unique code of the parent institution
4.5	`data.name`	Name of the sub-entity
4.6	`data.vaultId`	Vault identifier associated with the sub-entity
4.7	`data.kycStatus`	KYC verification status of the sub-entity (e.g. `DISABLED`)
4.8	`data.kycLevel`	KYC tier level assigned to the sub-entity (e.g. `TIER_1`)
4.9	`data.enabled`	Indicates whether the sub-entity is currently active (`true`/`false`)
4.10	`data.additionalInfo`	JSON string containing extra metadata (e.g. description and address)

Sample Response (Success)

{
  "success": true,
  "responseCode": "200",
  "responseMessage": "Success",
  "data": {
    "id": 78,
    "createdOn": "2026-05-20T21:58:03.4",
    "institutionId": 2,
    "institutionCode": "HYDR",
    "name": "Yaba Zone 1",
    "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 Already Exists For This Institution"
}