Create Branch

Overview

Create a new bank branch in the system with complete contact and address information.

Command Details

Command Name: CreateBranchCommand

Operation Type: Command (Write Operation)

Use Cases

• Branch Expansion: Register new branch locations
• Branch Network Setup: Initialize branch infrastructure
• Regional Operations: Establish branch presence in new areas
• Administrative Setup: Configure branch details for operations

API Endpoint

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

Request Structure

Request Body

{
  "commandName": "CreateBranchCommand",
  "data": {
    "key": "BR001",
    "name": "Main Branch",
    "contactInformation": {
      "emailAddress": "mainbranch@bank.com",
      "mobileNumber": "+234-123-456-7890"
    },
    "addressInformation": {
      "addressLine1": "123 Main Street",
      "addressLine2": "Suite 100",
      "addressCity": "Lagos",
      "addressState": "Lagos State",
      "addressCountry": "Nigeria",
      "zipCode": "100001"
    }
  }
}

Request Fields

Field Name	Type	Mandatory	Description
key	String	Yes	Unique branch code/identifier
name	String	Yes	Branch name
contactInformation	Object	Yes	Branch contact details
contactInformation.emailAddress	String	Yes	Branch email address
contactInformation.mobileNumber	String	Yes	Branch phone number
addressInformation	Object	Yes	Branch physical address
addressInformation.addressLine1	String	Yes	Primary address line
addressInformation.addressLine2	String	No	Secondary address line
addressInformation.addressCity	String	Yes	City name
addressInformation.addressState	String	Yes	State/Province
addressInformation.addressCountry	String	Yes	Country name
addressInformation.zipCode	String	Yes	Postal/ZIP code

Sample Requests

1. Standard Branch Creation

{
  "commandName": "CreateBranchCommand",
  "data": {
    "key": "BR001",
    "name": "Main Branch",
    "contactInformation": {
      "emailAddress": "mainbranch@bank.com",
      "mobileNumber": "+234-123-456-7890"
    },
    "addressInformation": {
      "addressLine1": "123 Main Street",
      "addressLine2": "Suite 100",
      "addressCity": "Lagos",
      "addressState": "Lagos State",
      "addressCountry": "Nigeria",
      "zipCode": "100001"
    }
  }
}

2. Regional Branch Creation

{
  "commandName": "CreateBranchCommand",
  "data": {
    "key": "BR-ABUJA-001",
    "name": "Abuja Central Branch",
    "contactInformation": {
      "emailAddress": "abuja@bank.com",
      "mobileNumber": "+234-987-654-3210"
    },
    "addressInformation": {
      "addressLine1": "Plot 456, Central Business District",
      "addressCity": "Abuja",
      "addressState": "Federal Capital Territory",
      "addressCountry": "Nigeria",
      "zipCode": "900001"
    }
  }
}

Response Structure

Success Response

{
  "isSuccessful": true,
  "statusCode": "00",
  "message": "Branch has been added successfully.",
  "data": {
    "id": 123,
    "name": "Main Branch",
    "key": "BR001",
    "encodedKey": "8a8e87e87d1234567890abcd",
    "objectState": 0,
    "objectStateDescription": "Active"
  }
}

Response Fields

Field Name	Type	Description
id	Integer	System-generated branch ID
name	String	Branch name
key	String	Branch code
encodedKey	String	Unique encoded identifier
objectState	Integer	Branch state (see ObjectStateEnum below)
objectStateDescription	String	Human-readable state description

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

Duplicate Branch Code

{
  "isSuccessful": false,
  "statusCode": "CBS_400",
  "message": "A branch with this code (BR001) already exists."
}

Validation Errors

{
  "isSuccessful": false,
  "statusCode": "CBS_400",
  "message": "Validation failed.",
  "errors": {
    "key": ["Branch code is required."],
    "name": ["Branch name is required."],
    "contactInformation.emailAddress": ["Valid email address is required."]
  }
}

Error Codes

Status Code	Message	Cause
CBS_400	Validation failed	Missing or invalid required fields
CBS_400	Branch code already exists	Duplicate branch code
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/cmd \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "commandName": "CreateBranchCommand",
    "data": {
      "key": "BR001",
      "name": "Main Branch",
      "contactInformation": {
        "emailAddress": "mainbranch@bank.com",
        "mobileNumber": "+234-123-456-7890"
      },
      "addressInformation": {
        "addressLine1": "123 Main Street",
        "addressCity": "Lagos",
        "addressState": "Lagos State",
        "addressCountry": "Nigeria",
        "zipCode": "100001"
      }
    }
  }'

C# Example

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

var request = new
{
    commandName = "CreateBranchCommand",
    data = new
    {
        key = "BR001",
        name = "Main Branch",
        contactInformation = new
        {
            emailAddress = "mainbranch@bank.com",
            mobileNumber = "+234-123-456-7890"
        },
        addressInformation = new
        {
            addressLine1 = "123 Main Street",
            addressCity = "Lagos",
            addressState = "Lagos State",
            addressCountry = "Nigeria",
            zipCode = "100001"
        }
    }
};

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

JavaScript/TypeScript Example

const response = await fetch('https://api.example.com/api/bpm/cmd', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${accessToken}`
  },
  body: JSON.stringify({
    commandName: 'CreateBranchCommand',
    data: {
      key: 'BR001',
      name: 'Main Branch',
      contactInformation: {
        emailAddress: 'mainbranch@bank.com',
        mobileNumber: '+234-123-456-7890'
      },
      addressInformation: {
        addressLine1: '123 Main Street',
        addressCity: 'Lagos',
        addressState: 'Lagos State',
        addressCountry: 'Nigeria',
        zipCode: '100001'
      }
    }
  })
});

const result = await response.json();

Best Practices

1. Unique Branch Codes: Ensure branch codes are unique and follow your organization's naming convention
2. Validation: Validate email addresses and phone numbers before submission
3. Address Completeness: Provide complete address information for accurate branch location
4. Error Handling: Implement proper error handling for duplicate codes
5. Audit Trail: Log branch creation activities for compliance

Related Commands

• Update Branch - Modify branch information
• Retrieve Branch List - Query branches
• Retrieve Branch By ID - Get branch details

---

Handler: AdministrationBranchCommandHandlers