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

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = 
    new AuthenticationHeaderValue("Bearer", accessToken);

var request = new
{
    queryName = "RetrieveBranchesListQuery",
    data = new
    {
        pageNumber = 1,
        pageSize = 50,
        status = new[] { 0 },
        filters = new[]
        {
            new
            {
                propertyName = "Name",
                @operator = "Contains",
                value = "Lagos"
            }
        }
    }
};

var response = await client.PostAsJsonAsync(
    "https://api.example.com/api/bpm/qry", 
    request
);
var result = await response.Content.ReadFromJsonAsync<ApiResponse>();

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

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

Related APIs

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

---

Handler: AdministrationBranchCommandHandlers