Skip to Content
C-Tax v1.0 is now available
API ReferenceInsurances API

Branch Insurances API

Manage branch insurance configurations synced with KRA eTIMS/VSCU system.

Overview

The Insurances API allows you to manage insurance configurations for branches. These insurances can be applied to sales transactions and are synced with the VSCU system.

List Insurances

Get all insurances for a branch.

GET/api/v1/insurances

List Insurances

Retrieve all insurance configurations for a branch.

Authentication
Parameters
bhf_id*
string · query

Branch identifier

status
string · query

Filter by status (active, inactive, all)

Response

Status: 200 OK

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "isrccCd": "INS001",
      "isrccNm": "Health Insurance",
      "isrcRt": 2.5,
      "useYn": "Y",
      "regrNm": "John Doe",
      "regrId": "user123",
      "created_at": "2024-01-15T10:00:00Z"
    }
  ],
  "meta": {
    "total": 5,
    "timestamp": "2024-01-15T14:30:00Z"
  }
}

Create Insurance

Create or update branch insurance.

POST/api/v1/insurances

Create Insurance

Create a new insurance configuration and optionally sync to VSCU.

Authentication
Request BodyJSON

Field Descriptions

FieldTypeRequiredDescription
bhf_idstringYesBranch identifier
isrccCdstringYesInsurance code (max 50 chars)
isrccNmstringYesInsurance name (max 255 chars)
isrcRtnumberYesInsurance rate (0-100%)
useYnstringNoUse status (Y/N, default: Y)
regrNmstringNoRegistrant name
regrIdstringNoRegistrant ID
sync_to_vscubooleanNoSync to VSCU (default: true)

Response

Status: 201 Created

{
  "status": "success",
  "message": "Insurance saved successfully",
  "data": {
    "id": 1,
    "isrccCd": "INS001",
    "isrccNm": "Health Insurance",
    "isrcRt": 2.5,
    "useYn": "Y"
  },
  "meta": {
    "synced_to_vscu": true,
    "vscu_response": {...}
  }
}

Get Insurance Details

Retrieve a specific insurance.

GET/api/v1/insurances/{id}

Get Insurance Details

Retrieve detailed information about a specific insurance.

Authentication
Parameters
id*
number · path

Insurance ID

Response

Status: 200 OK

{
  "status": "success",
  "data": {
    "id": 1,
    "branch_id": 1,
    "isrccCd": "INS001",
    "isrccNm": "Health Insurance",
    "isrcRt": 2.5,
    "useYn": "Y",
    "regrNm": "John Doe",
    "regrId": "user123",
    "modrNm": "Jane Doe",
    "modrId": "user456",
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T14:30:00Z"
  }
}

Update Insurance

Update an existing insurance.

PUT/api/v1/insurances/{id}

Update Insurance

Update an existing insurance configuration.

Authentication
Parameters
id*
number · path

Insurance ID

Request BodyJSON

Response

Status: 200 OK

{
  "status": "success",
  "message": "Insurance updated successfully",
  "data": {
    "id": 1,
    "isrccCd": "INS001",
    "isrccNm": "Updated Health Insurance",
    "isrcRt": 3.0,
    "useYn": "Y"
  },
  "meta": {
    "synced_to_vscu": true
  }
}

Delete Insurance

Delete an insurance.

DELETE/api/v1/insurances/{id}

Delete Insurance

Delete an insurance configuration.

Authentication
Parameters
id*
number · path

Insurance ID

Response

Status: 200 OK

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

Toggle Insurance Status

Activate or deactivate an insurance.

POST/api/v1/insurances/{id}/toggle

Toggle Insurance Status

Activate or deactivate an insurance configuration.

Authentication
Parameters
id*
number · path

Insurance ID

Request BodyJSON

Response

Status: 200 OK

{
  "status": "success",
  "message": "Insurance activated successfully",
  "data": {
    "id": 1,
    "useYn": "Y"
  }
}

Code Examples

JavaScript

const axios = require('axios');
 
const apiKey = process.env.CTAX_API_KEY;
const baseURL = 'https://c-tax.1809ltd.co.ke/api/v1';
 
// Create insurance
const response = await axios.post(`${baseURL}/insurances`, {
  bhf_id: '00',
  isrccCd: 'INS001',
  isrccNm: 'Health Insurance',
  isrcRt: 2.5,
  useYn: 'Y',
  sync_to_vscu: true
}, {
  headers: { Authorization: `Bearer ${apiKey}` }
});
 
console.log('Insurance created:', response.data.data);
 
// List insurances
const list = await axios.get(`${baseURL}/insurances?bhf_id=00&status=active`, {
  headers: { Authorization: `Bearer ${apiKey}` }
});
 
// Toggle status
await axios.post(`${baseURL}/insurances/${id}/toggle`, {}, {
  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',
    ],
]);
 
// Create insurance
$response = $client->post('insurances', [
    'json' => [
        'bhf_id' => '00',
        'isrccCd' => 'INS001',
        'isrccNm' => 'Health Insurance',
        'isrcRt' => 2.5,
        'useYn' => 'Y',
        'sync_to_vscu' => true,
    ],
]);
 
$result = json_decode($response->getBody(), true);
echo "Insurance created: {$result['data']['isrccNm']}\n";
 
// List insurances
$list = $client->get('insurances?bhf_id=00&status=active');
 
// Toggle status
$client->post('insurances/1/toggle');

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}'}
 
# Create insurance
response = requests.post(
    f'{base_url}/insurances',
    json={
        'bhf_id': '00',
        'isrccCd': 'INS001',
        'isrccNm': 'Health Insurance',
        'isrcRt': 2.5,
        'useYn': 'Y',
        'sync_to_vscu': True
    },
    headers=headers
)
print(f"Insurance created: {response.json()['data']['isrccNm']}")
 
# List insurances
insurances = requests.get(
    f'{base_url}/insurances?bhf_id=00&status=active',
    headers=headers
)
 
# Toggle status
requests.post(f'{base_url}/insurances/1/toggle', headers=headers)

Best Practices

  1. Sync to VSCU - Always sync insurance changes to VSCU for compliance
  2. Unique Codes - Use unique insurance codes per branch
  3. Valid Rates - Ensure rates are between 0-100%
  4. Track Changes - Monitor who created/modified insurances using regrNm/modrNm
  5. Regular Updates - Keep insurance rates up to date with current regulations
Last updated on
Notices APICode Data API