Branches API

Manage business branches and locations for your client account.

Overview

Branches represent physical business locations that process transactions. Each branch can have its own VSCU device, inventory, customers, and users. The main branch is typically 00.

List Branches

Get all branches for your account. This endpoint also syncs branches from KRA/VSCU if a device is configured.

GET/api/v1/branches

List Branches

Retrieve all branches for your client account. If a VSCU device is configured, it will also sync any new branches from KRA.

Authentication

Response

Status: 200 OK


{
  "status": "success",
  "data": [
    {
      "id": 1,
      "bhf_id": "00",
      "name": "Head Office",
      "location": "Westlands, Nairobi",
      "contact_person": "John Doe",
      "contact_phone": "+254712345678",
      "is_active": true,
      "has_device": true,
      "device_active": true,
      "device_serial": "VSCU-KE-001",
      "created_at": "2025-01-15T10:00:00Z"
    },
    {
      "id": 2,
      "bhf_id": "01",
      "name": "Mombasa Branch",
      "location": "Moi Avenue, Mombasa",
      "contact_person": "Jane Smith",
      "contact_phone": "+254722345678",
      "is_active": true,
      "has_device": true,
      "device_active": true,
      "device_serial": "VSCU-KE-002",
      "created_at": "2025-01-16T10:00:00Z"
    }
  ],
  "meta": {
    "total": 2,
    "timestamp": "2025-01-15T14:30:00Z"
  }
}

Create Branch

Create a new branch for your account.

POST/api/v1/branches

Create Branch

Create a new branch for your client account.

Authentication

Request BodyJSON

Field Descriptions

Field	Type	Required	Description
`bhf_id`	string	Yes	Unique branch identifier (2 chars: “00”-“99”)
`name`	string	Yes	Branch name (max 255 chars)
`location`	string	No	Physical location/address (max 500 chars)
`contact_person`	string	No	Branch contact person name (max 255 chars)
`contact_phone`	string	No	Contact phone number (max 50 chars)
`metadata`	object	No	Additional custom metadata

Response

Status: 201 Created


{
  "status": "success",
  "message": "Branch created successfully",
  "data": {
    "id": 3,
    "bhf_id": "02",
    "name": "Kisumu Branch",
    "location": "Oginga Odinga Street, Kisumu",
    "contact_person": "Alice Johnson",
    "contact_phone": "+254733345678",
    "is_active": true,
    "created_at": "2025-01-17T10:00:00Z"
  },
  "meta": {
    "timestamp": "2025-01-17T10:00:00Z",
    "request_id": "req_abc123"
  }
}

Get Branch Details

Retrieve details of a specific branch including VSCU device info and recent transactions.

GET/api/v1/branches/{bhfId}

Get Branch Details

Retrieve detailed information about a specific branch, including device and recent transaction data.

Authentication

Parameters

bhfId*

string · path

Branch identifier (e.g., '00', '01')

Response

Status: 200 OK


{
  "status": "success",
  "data": {
    "id": 1,
    "bhf_id": "00",
    "name": "Head Office",
    "location": "Westlands, Nairobi",
    "contact_person": "John Doe",
    "contact_phone": "+254712345678",
    "is_active": true,
    "metadata": {
      "region": "Central"
    },
    "device": {
      "id": 1,
      "dvc_srl_no": "VSCU-KE-001",
      "tin": "P000123456X",
      "vscu_url": "http://vscu-server:8080",
      "is_active": true,
      "last_initialized_at": "2025-01-15T10:00:00Z",
      "device_info": {}
    },
    "recent_transactions": [
      {
        "id": "uuid-123",
        "type": "sales",
        "invoice_no": "INV-001",
        "status": "success",
        "created_at": "2025-01-15T14:00:00Z"
      }
    ],
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-01-15T14:30:00Z"
  }
}

Status: 404 Not Found


{
  "status": "error",
  "message": "Branch not found"
}

Update Branch

Update an existing branch. Supports both PUT and PATCH methods.

PUT/api/v1/branches/{bhfId}

Update Branch

Update branch information. All fields are optional - only provided fields will be updated.

Authentication

Parameters

bhfId*

string · path

Branch identifier

Request BodyJSON

Response

Status: 200 OK


{
  "status": "success",
  "message": "Branch updated successfully",
  "data": {
    "id": 1,
    "bhf_id": "00",
    "name": "Head Office - Updated",
    "location": "New Address, Westlands, Nairobi",
    "contact_person": "John Doe Jr.",
    "contact_phone": "+254712999999",
    "is_active": true,
    "metadata": {},
    "updated_at": "2025-01-17T15:00:00Z"
  }
}

Delete Branch

Delete a branch (soft delete).

DELETE/api/v1/branches/{bhfId}

Delete Branch

Soft delete a branch. The main branch (00) cannot be deleted.

Authentication

Parameters

bhfId*

string · path

Branch identifier to delete

Response

Status: 200 OK


{
  "status": "success",
  "message": "Branch deleted successfully"
}

Note: The main branch (00) cannot be deleted. Branches with active transactions or devices cannot be deleted until those resources are removed or transferred.

Get Branch Statistics

Get transaction statistics for a specific branch.

GET/api/v1/branches/{bhfId}/stats

Get Branch Statistics

Retrieve transaction statistics and performance metrics for a branch.

Authentication

Parameters

bhfId*

string · path

Branch identifier

Response

Status: 200 OK


{
  "status": "success",
  "data": {
    "branch": {
      "id": 1,
      "bhf_id": "00",
      "name": "Head Office"
    },
    "statistics": {
      "total_transactions": 1250,
      "successful_transactions": 1200,
      "failed_transactions": 30,
      "pending_transactions": 20,
      "sales_count": 850,
      "purchases_count": 300,
      "stock_movements_count": 100,
      "today_transactions": 45,
      "this_month_transactions": 420
    },
    "generated_at": "2025-01-15T14:30:00Z"
  }
}

Error Responses

400 Bad Request


{
  "status": "error",
  "message": "Validation failed",
  "errors": {
    "bhf_id": ["The bhf_id field must be at most 10 characters."]
  }
}

404 Not Found


{
  "status": "error",
  "message": "Branch not found"
}

409 Conflict


{
  "status": "error",
  "message": "Branch with this bhf_id already exists"
}

Code Examples

JavaScript


const axios = require('axios');
 
const apiKey = process.env.CTAX_API_KEY;
const baseURL = 'https://c-tax.1809ltd.co.ke/api/v1';
 
// List all branches
const branches = await axios.get(`${baseURL}/branches`, {
  headers: { Authorization: `Bearer ${apiKey}` }
});
 
// Create a new branch
const newBranch = await axios.post(`${baseURL}/branches`, {
  bhf_id: '02',
  name: 'Kisumu Branch',
  location: 'Oginga Odinga Street, Kisumu',
  contact_person: 'Alice Johnson',
  contact_phone: '+254733345678'
}, {
  headers: { Authorization: `Bearer ${apiKey}` }
});
 
// Get branch statistics
const stats = await axios.get(`${baseURL}/branches/00/stats`, {
  headers: { Authorization: `Bearer ${apiKey}` }
});

PHP


use GuzzleHttp\Client;
 
$client = new Client([
    'base_uri' => 'https://c-tax.1809ltd.co.ke/api/v1/',
    'headers' => [
        'Authorization' => 'Bearer ' . env('CTAX_API_KEY'),
        'Content-Type' => 'application/json',
    ],
]);
 
// List all branches
$branches = $client->get('branches');
 
// Create a new branch
$response = $client->post('branches', [
    'json' => [
        'bhf_id' => '02',
        'name' => 'Kisumu Branch',
        'location' => 'Oginga Odinga Street, Kisumu',
    ],
]);

Python


import requests
import os
 
api_key = os.environ['CTAX_API_KEY']
base_url = 'https://c-tax.1809ltd.co.ke/api/v1'
headers = {'Authorization': f'Bearer {api_key}'}
 
# List all branches
response = requests.get(f'{base_url}/branches', headers=headers)
branches = response.json()['data']
 
# Create a new branch
new_branch = requests.post(
    f'{base_url}/branches',
    json={
        'bhf_id': '02',
        'name': 'Kisumu Branch',
        'location': 'Oginga Odinga Street, Kisumu',
    },
    headers=headers
)

Branch Relationships

Each branch can have:

Relationship	Description
VscuDevice	One VSCU device for tax compliance
Transactions	All transactions (sales, purchases, stock)
Items	Branch-specific inventory items
Notices	KRA notices for this branch
Insurances	Branch insurance configurations

Best Practices

Unique Branch IDs - Use 2-character codes (00-99), starting with 00 for main branch
Complete Information - Provide contact details for each branch
Configure Devices First - Set up VSCU device before processing transactions
Monitor Statistics - Regularly check branch performance
Keep Records Updated - Maintain accurate branch information
Test Before Production - Use sandbox environment to test branch setup

Devices API - Configure branch VSCU devices
Sales API - Process sales for a branch
Items API - Manage branch inventory
Transactions API - View branch transactions
Notices API - Branch KRA notices

Branches API

Overview

List Branches

List Branches

Response

Create Branch

Create Branch

Field Descriptions

Response

Get Branch Details

Get Branch Details

Response

Update Branch

Update Branch

Response

Delete Branch

Delete Branch

Response

Get Branch Statistics

Get Branch Statistics

Response

Error Responses

400 Bad Request

404 Not Found

409 Conflict

Code Examples

JavaScript

PHP

Python

Branch Relationships

Best Practices

Related Endpoints