Get Branch Vault List

Overview

Retrieves a list of all vaults associated with a branch or all branches, with filtering options.

Command

GetBranchVaultListQuery

Endpoint

POST /api/bpm/cmd

Request Headers

Authorization: Bearer {access_token}
Content-Type: application/json
X-Tenant-Id: {tenant_id}

Request Body

{
  "cmd": "GetBranchVaultListQuery",
  "data": {
    "branchId": "BRANCH-001",
    "currencyCode": "NGN",
    "status": "Active",
    "pageNumber": 1,
    "pageSize": 20
  }
}

Request Parameters

Parameter	Type	Required	Description
cmd	string	Yes	Must be "GetBranchVaultListQuery"
data	object	Yes	Query filter data
↳ branchId	string	No	Filter by specific branch ID. If omitted, returns vaults for all branches
↳ currencyCode	string	No	Filter by currency code (e.g., "NGN", "USD")
↳ status	string	No	Filter by vault status (Active, Inactive, Suspended)
↳ pageNumber	integer	No	Page number for pagination (default: 1)
↳ pageSize	integer	No	Number of records per page (default: 20)

Response

Success Response (200 OK)

{
  "success": true,
  "message": "Vault list retrieved successfully",
  "data": {
    "vaults": [
      {
        "vaultId": "string",
        "branchId": "string",
        "branchName": "string",
        "vaultName": "string",
        "currencyCode": "string",
        "currentBalance": "decimal",
        "maximumBalance": "decimal",
        "minimumBalance": "decimal",
        "status": "string",
        "requiresApproval": "boolean",
        "createdDate": "datetime",
        "lastTransactionDate": "datetime"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "pageSize": 20,
      "totalRecords": 50,
      "totalPages": 3
    }
  }
}

Error Responses

400 Bad Request

{
  "success": false,
  "message": "Invalid filter parameters",
  "errors": [
    "Invalid page number",
    "Invalid currency code"
  ]
}

404 Not Found

{
  "success": false,
  "message": "No vaults found matching the criteria"
}

Business Rules

1. Users can only view vaults for branches they have access to
2. Results are sorted by branch name and then vault name
3. Inactive vaults are included in results unless filtered out
4. Balance information shows real-time values
5. Maximum page size is 100 records

Code Example

async function getBranchVaultList(filters = {}) {
  const response = await fetch('/api/bpm/cmd', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
      'X-Tenant-Id': tenantId
    },
    body: JSON.stringify({
      commandType: 'GetBranchVaultListQuery',
      data: {
        branchId: filters.branchId,
        currencyCode: filters.currencyCode || 'NGN',
        status: 'Active',
        pageNumber: 1,
        pageSize: 50
      }
    })
  });
  
  return await response.json();
}

Related Commands

• Create Branch Vault - Create new vault
• Update Branch Vault - Modify vault settings
• Fund Branch Vault Account - Add funds to vault

Notes

• Use filters to improve query performance for large organizations
• Monitor vault balances regularly to ensure adequate liquidity
• Consider caching vault list for frequently accessed branches
• Export results for reconciliation and reporting purposes