Retrieve Branch List

Overview

The Retrieve Branch List API allows financial institutions to fetch a list of all branches with advanced filtering, pagination, and export options. This query returns comprehensive branch information for administrative and operational purposes.

Command Details

Command Name: RetrieveBranchesListQuery

Operation Type: Query (Read Operation)

Use Cases

Branch Directory: Display all available branches in the system
Branch Selection: Provide branch lists for dropdown selections in forms
Administrative Reports: Generate reports showing all branch locations
Branch Filtering: Search and filter branches by specific criteria
Data Export: Export branch data to Excel for analysis

API Endpoint

POST /api/bpm/qry
Content-Type: application/json
Authorization: Bearer {access_token}

Request Structure

Request Body

{
  "queryName": "RetrieveBranchesListQuery",
  "data": {
    "pageNumber": 1,
    "pageSize": 50,
    "searchText": "Lagos",
    "id": 123,
    "status": [0, 1],
    "startDate": "2025-01-01",
    "endDate": "2025-12-31",
    "isExport": false,
    "filters": [
      {
        "propertyName": "Name",
        "operator": "Contains",
        "value": "Main"
      }
    ]
  }
}

Request Fields

Field Name	Type	Mandatory	Description
`pageNumber`	Integer	No	Page number for pagination (default: 1)
`pageSize`	Integer	No	Number of records per page (default: 10)
`searchText`	String	No	Search text to filter branches by name
`id`	Integer	No	Specific branch ID to retrieve
`status`	Integer[]	No	Array of ObjectStateEnum values to filter by state
`startDate`	String	No	Filter branches created on or after this date (format: YYYY-MM-DD)
`endDate`	String	No	Filter branches created on or before this date (format: YYYY-MM-DD)
`isExport`	Boolean	No	If true, exports all results to Excel (ignores pagination)
`filters`	Object[]	No	Advanced filter criteria using DynamicPredicateBuilder

Advanced Filtering

DynamicPredicateBuilder

This query supports advanced filtering through the filters array. You can apply complex filter conditions on any Branch property.

Filter Structure

Field Name	Type	Description
`propertyName`	String	Name of the property to filter (e.g., "Name", "Key", "DateCreated")
`operator`	String	Comparison operator (see below)
`value`	Any	Value to compare against
`logicalOperator`	String	Optional: "And" or "Or" (default: "And")

Supported Operators

Equals - Exact match
NotEquals - Not equal to
Contains - String contains (case-insensitive)
StartsWith - String starts with
EndsWith - String ends with
GreaterThan - Greater than (numbers/dates)
GreaterThanOrEqual - Greater than or equal
LessThan - Less than (numbers/dates)
LessThanOrEqual - Less than or equal
In - Value is in array
NotIn - Value is not in array

Filter Examples

Example 1: Filter by Branch Name Contains

{
  "queryName": "RetrieveBranchesListQuery",
  "data": {
    "pageNumber": 1,
    "pageSize": 20,
    "filters": [
      {
        "propertyName": "Name",
        "operator": "Contains",
        "value": "Lagos"
      }
    ]
  }
}

Example 2: Multiple Filter Conditions

{
  "queryName": "RetrieveBranchesListQuery",
  "data": {
    "filters": [
      {
        "propertyName": "Name",
        "operator": "Contains",
        "value": "Branch",
        "logicalOperator": "And"
      },
      {
        "propertyName": "ObjectState",
        "operator": "Equals",
        "value": 0
      }
    ]
  }
}

Example 3: Filter by Date Range

{
  "queryName": "RetrieveBranchesListQuery",
  "data": {
    "startDate": "2025-01-01",
    "endDate": "2025-06-30",
    "filters": [
      {
        "propertyName": "Name",
        "operator": "StartsWith",
        "value": "BR"
      }
    ]
  }
}

Data Export

Export to Excel

Set isExport: true to export all matching results to an Excel file. When exporting:

Pagination is ignored (all matching records are included)
Returns Excel file data
Maximum records: Limited by system configuration

Export Request Example

{
  "queryName": "RetrieveBranchesListQuery",
  "data": {
    "isExport": true,
    "status": [0],
    "startDate": "2025-01-01",
    "endDate": "2025-12-31"
  }
}

Sample Requests

1. Standard Branch List Query

{
  "queryName": "RetrieveBranchesListQuery",
  "data": {
    "pageNumber": 1,
    "pageSize": 50
  }
}

2. Search Branches by Name

{
  "queryName": "RetrieveBranchesListQuery",
  "data": {
    "pageNumber": 1,
    "pageSize": 20,
    "searchText": "Lagos"
  }
}

3. Filter by Status (Active Only)

{
  "queryName": "RetrieveBranchesListQuery",
  "data": {
    "pageNumber": 1,
    "pageSize": 50,
    "status": [0]
  }
}

4. Filter by Date Range

{
  "queryName": "RetrieveBranchesListQuery",
  "data": {
    "pageNumber": 1,
    "pageSize": 50,
    "startDate": "2025-01-01",
    "endDate": "2025-12-31"
  }
}

5. Get Specific Branch by ID

{
  "queryName": "RetrieveBranchesListQuery",
  "data": {
    "id": 123
  }
}

Response Structure

Success Response

{
  "isSuccessful": true,
  "statusCode": "00",
  "message": "50/150 records returned.",
  "data": {
    "items": [
      {
        "id": 123,
        "name": "Main Branch",
        "key": "BR001",
        "branchNote": "Primary branch location",
        "dateCreated": "2025-01-15T10:30:00Z",
        "lastUpdated": "2025-01-15T10:30:00Z",
        "contactInformation": {
          "emailAddress": "mainbranch@bank.com",
          "mobileNumber": "+234-123-456-7890"
        },
        "address": {
          "addressCity": "Lagos",
          "addressCountry": "Nigeria",
          "addressLine1": "123 Main Street",
          "addressLine2": "Suite 100",
          "addressState": "Lagos State",
          "zipCode": "100001"
        },
        "objectState": 0,
        "objectStateDescription": "Active",
        "encodedKey": "8a8e87e87d1234567890abcd"
      }
    ],
    "pageNumber": 1,
    "pageSize": 50,
    "totalPages": 3,
    "totalRecords": 150
  },
  "pages": 3,
  "hasNext": true,
  "size": 50,
  "hasPrevious": false,
  "count": 150
}

Response Fields

Field Name	Type	Description
`items`	Array	List of branch objects
`items[].id`	Integer	Branch ID
`items[].name`	String	Branch name
`items[].key`	String	Branch code
`items[].branchNote`	String	Branch notes/description
`items[].dateCreated`	String	Creation date (ISO 8601)
`items[].lastUpdated`	String	Last update date (ISO 8601)
`items[].contactInformation`	Object	Contact details
`items[].address`	Object	Physical address
`items[].objectState`	Integer	Branch state (see ObjectStateEnum)
`items[].objectStateDescription`	String	Human-readable state
`items[].encodedKey`	String	Unique encoded identifier
`pageNumber`	Integer	Current page number
`pageSize`	Integer	Records per page
`totalPages`	Integer	Total number of pages
`totalRecords`	Integer	Total matching records
`hasNext`	Boolean	Whether next page exists
`hasPrevious`	Boolean	Whether previous page exists

Enumerations

ObjectStateEnum

Value	Name	Description
0	Active	Branch is active and operational
1	NotActive	Branch is not active
2	Deleted	Branch has been deleted

Error Handling

Common Error Responses

Validation Errors

{
  "isSuccessful": false,
  "statusCode": "CBS_400",
  "message": "Invalid filter parameters."
}

Error Codes

Status Code	Message	Cause
`CBS_400`	Invalid request	Malformed filter criteria
`CBS_401`	Unauthorized	Invalid authentication token
`CBS_403`	Forbidden	Insufficient permissions
`CBS_500`	Internal server error	System error

Code Examples

cURL

curl -X POST https://api.example.com/api/bpm/qry \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "queryName": "RetrieveBranchesListQuery",
    "data": {
      "pageNumber": 1,
      "pageSize": 50,
      "status": [0]
    }
  }'

C# Example

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

JavaScript/TypeScript Example

const response = await fetch('https://api.example.com/api/bpm/qry', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${accessToken}`
  },
  body: JSON.stringify({
    queryName: 'RetrieveBranchesListQuery',
    data: {
      pageNumber: 1,
      pageSize: 50,
      status: [0],
      filters: [
        {
          propertyName: 'Name',
          operator: 'Contains',
          value: 'Lagos'
        }
      ]
    }
  })
});

const result = await response.json();

Best Practices

Pagination: Use appropriate page sizes for optimal performance (default: 10, max recommended: 100)
Filtering: Use specific filters to reduce data transfer
Export: Use export feature for reporting, not real-time queries
Date Ranges: Specify date ranges to limit result sets
Search Text: Combine with filters for refined searches
Caching: Results are cached for performance

Create Branch - Create new branch
Update Branch - Update branch information
Retrieve Branch By ID - Get specific branch details

Handler: AdministrationBranchCommandHandlers

Overview​

Command Details​

Use Cases​

API Endpoint​

Request Structure​

Request Body​

Request Fields​

Advanced Filtering​

DynamicPredicateBuilder​

Filter Structure​

Supported Operators​

Filter Examples​

Example 1: Filter by Branch Name Contains​

Example 2: Multiple Filter Conditions​

Example 3: Filter by Date Range​

Data Export​

Export to Excel​

Export Request Example​

Sample Requests​

1. Standard Branch List Query​

2. Search Branches by Name​

3. Filter by Status (Active Only)​

4. Filter by Date Range​

5. Get Specific Branch by ID​

Response Structure​

Success Response​

Response Fields​

Enumerations​

ObjectStateEnum​

Error Handling​

Common Error Responses​

Validation Errors​

Error Codes​

Code Examples​

cURL​

C# Example​

JavaScript/TypeScript Example​

Best Practices​

Related APIs​