Retrieve Branch By ID

Overview

The Retrieve Branch By ID API allows financial institutions to fetch detailed information about a specific branch using its unique identifier. This query returns comprehensive branch data including contact information, location details, and operational status.

Command Details

Command Name: RetrieveBranchByIdQuery

Operation Type: Query (Read Operation)

Use Cases

• Branch Details View: Display complete information for a specific branch
• Branch Verification: Validate branch existence and status before transactions
• Administrative Management: Access branch details for updates or reviews
• Reporting: Include branch information in transaction or operational reports

API Endpoint

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

Request Structure

Request Body

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

Request Fields

Field Name	Type	Mandatory	Description
id	Integer	Yes	Branch ID

Sample Requests

1. Standard Branch Retrieval

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

Response Structure

Success Response

{
  "isSuccessful": true,
  "statusCode": "00",
  "message": "Branch with ID 123 found.",
  "data": {
    "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"
  }
}

Response Fields

Field Name	Type	Description
id	Integer	Branch ID
name	String	Branch name
key	String	Branch code
branchNote	String	Branch notes/description
dateCreated	String	Creation date (ISO 8601)
lastUpdated	String	Last update date (ISO 8601)
contactInformation	Object	Contact details
contactInformation.emailAddress	String	Branch email address
contactInformation.mobileNumber	String	Branch phone number
address	Object	Physical address details
address.addressCity	String	City name
address.addressCountry	String	Country name
address.addressLine1	String	Primary address line
address.addressLine2	String	Secondary address line (optional)
address.addressState	String	State/Province
address.zipCode	String	Postal/ZIP code
objectState	Integer	Branch state (see ObjectStateEnum)
objectStateDescription	String	Human-readable state description
encodedKey	String	Unique encoded identifier

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

1. Branch Not Found

{
  "isSuccessful": false,
  "statusCode": "CBS_404",
  "message": "Branch with ID 123 not found."
}

2. Invalid Branch ID

{
  "isSuccessful": false,
  "statusCode": "CBS_400",
  "message": "Invalid branch ID format."
}

Error Codes

Status Code	Message	Cause
CBS_400	Invalid request	Malformed branch ID
CBS_401	Unauthorized	Invalid authentication token
CBS_403	Forbidden	Insufficient permissions
CBS_404	Branch not found	Branch does not exist
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": "RetrieveBranchByIdQuery",
    "data": {
      "id": 123
    }
  }'

C# Example

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

var request = new
{
    queryName = "RetrieveBranchByIdQuery",
    data = new
    {
        id = 123
    }
};

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: 'RetrieveBranchByIdQuery',
    data: {
      id: 123
    }
  })
});

const result = await response.json();

Best Practices

1. Validation: Verify branch ID is valid before making the request
2. Error Handling: Implement proper error handling for branch not found scenarios
3. Caching: Consider caching branch information for frequently accessed branches
4. Permissions: Ensure user has appropriate permissions to view branch data

Notes

• Branch ID is required and must be valid
• Returns complete branch information including audit fields
• Inactive branches can still be retrieved
• Requires appropriate user permissions to view branch data
• This query internally uses RetrieveBranchesListQuery with ID filter

Related APIs

• Create Branch - Create new branch
• Update Branch - Update branch information
• Retrieve Branch List - Query multiple branches
• Retrieve Allowable Branches - Get user-accessible branches

---

Handler: AdministrationBranchCommandHandlers