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

Code Data API

Manage code classifications and synchronize reference data from VSCU system.

Overview

The Code Data API provides access to various code classifications used throughout the system, including tax types, payment methods, countries, currencies, and more. These codes are synchronized from the VSCU system and stored locally for fast access.

Sync Codes

Synchronize code classifications from VSCU to the local database.

POST/api/v1/codes/sync

Sync Codes

Synchronize code classifications from VSCU to the local database. This fetches all reference data needed for transactions.

Authentication
Request BodyJSON

Field Descriptions

FieldTypeRequiredDescription
bhf_idstringYesBranch identifier
last_req_dtstringNoLast request datetime in YYYYMMDDHHmmss format (default: “20180520000000”)

Response

Status: 200 OK

{
  "status": "success",
  "message": "Codes synced successfully",
  "data": {
    "synced_classes": 18,
    "synced_details": 245,
    "synced_at": "2024-01-15T14:30:30Z"
  }
}

Error Responses

404 Not Found - Branch not found:

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

400 Bad Request - VSCU device not configured:

{
  "status": "error",
  "message": "VSCU device not configured for this branch"
}

Get All Code Classifications

Retrieve all code classifications with their details.

GET/api/v1/codes

Get All Codes

Retrieve all code classifications with their details.

Authentication
Parameters
status
string · query

Filter by status: active, inactive, or all (default: active)

Response

Status: 200 OK

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "cd_cls": "04",
      "cd_cls_nm": "Taxation Type",
      "cd_cls_desc": "Tax classification codes",
      "use_yn": "Y",
      "user_dfn_nm1": null,
      "user_dfn_nm2": null,
      "user_dfn_nm3": null,
      "last_synced_at": "2024-01-15T14:30:30Z",
      "active_details": [
        {
          "id": 1,
          "code_class_id": 1,
          "cd": "A",
          "cd_nm": "Exempted",
          "cd_desc": "Tax exempted items",
          "use_yn": "Y",
          "srt_ord": 1,
          "user_dfn_cd1": null,
          "user_dfn_cd2": null,
          "user_dfn_cd3": null
        }
      ]
    }
  ],
  "meta": {
    "total": 18,
    "timestamp": "2024-01-15T14:30:30Z"
  }
}

Get Specific Code Class

Retrieve a specific code classification by its code.

GET/api/v1/codes/{cdCls}

Get Code Class

Retrieve a specific code classification by its code.

Authentication
Parameters
cdCls*
string · path

Code class identifier (e.g., '04', '05', '08')

Response

Status: 200 OK

{
  "status": "success",
  "data": {
    "id": 1,
    "cd_cls": "04",
    "cd_cls_nm": "Taxation Type",
    "cd_cls_desc": "Tax classification codes",
    "use_yn": "Y",
    "details": [
      {
        "id": 1,
        "cd": "A",
        "cd_nm": "Exempted",
        "cd_desc": "Tax exempted items",
        "use_yn": "Y",
        "srt_ord": 1
      }
    ]
  }
}

404 Not Found:

{
  "status": "error",
  "message": "Code class not found"
}

Get Tax Types

Retrieve tax type codes (Taxation Type - cdCls: 04).

GET/api/v1/codes/tax-types

Get Tax Types

Retrieve tax type codes used for classifying items by tax category.

Authentication

Response

Status: 200 OK

{
  "status": "success",
  "data": [
    {
      "code": "A",
      "name": "Exempted",
      "description": "Tax exempted items",
      "user_defined_1": null,
      "user_defined_2": null,
      "user_defined_3": null,
      "sort_order": 1
    },
    {
      "code": "B",
      "name": "Standard Rate",
      "description": "16% VAT",
      "user_defined_1": null,
      "user_defined_2": null,
      "user_defined_3": null,
      "sort_order": 2
    }
  ],
  "meta": {
    "total": 5,
    "code_class": "Taxation Type",
    "last_synced": "2024-01-15T14:30:30Z",
    "timestamp": "2024-01-15T14:30:30Z"
  }
}

Get Countries

Retrieve country codes (Country - cdCls: 05).

GET/api/v1/codes/countries

Get Countries

Retrieve country codes for origin/destination classification.

Authentication

Get Payment Types

Retrieve payment type codes (Payment Type - cdCls: 03).

GET/api/v1/codes/payment-types

Get Payment Types

Retrieve payment type codes used in sales and purchase transactions.

Authentication

Response Example

{
  "status": "success",
  "data": [
    {
      "code": "01",
      "name": "Cash",
      "description": "Cash payment",
      "user_defined_1": null,
      "user_defined_2": null,
      "user_defined_3": null,
      "sort_order": 1
    },
    {
      "code": "02",
      "name": "Card",
      "description": "Card payment",
      "user_defined_1": null,
      "user_defined_2": null,
      "user_defined_3": null,
      "sort_order": 2
    }
  ],
  "meta": {
    "total": 10,
    "code_class": "Payment Type",
    "last_synced": "2024-01-15T14:30:30Z",
    "timestamp": "2024-01-15T14:30:30Z"
  }
}

Get Packaging Units

Retrieve packaging unit codes (Packing Unit - cdCls: 17).

GET/api/v1/codes/packaging-units

Get Packaging Units

Retrieve packaging unit codes for item classification.

Authentication

Get Quantity Units

Retrieve quantity unit codes (Quantity Unit - cdCls: 10).

GET/api/v1/codes/quantity-units

Get Quantity Units

Retrieve quantity/measurement unit codes.

Authentication

Get Item Types

Retrieve item type codes (Item Type - cdCls: 09).

GET/api/v1/codes/item-types

Get Item Types

Retrieve item type codes (Raw Material, Finished Product, Service).

Authentication

Get Currencies

Retrieve currency codes (Currency - cdCls: 11).

GET/api/v1/codes/currencies

Get Currencies

Retrieve currency codes for multi-currency transactions.

Authentication

Response Example

{
  "status": "success",
  "data": [
    {
      "code": "KES",
      "name": "Kenyan Shilling",
      "description": "Kenya Shilling",
      "user_defined_1": null,
      "user_defined_2": null,
      "user_defined_3": null,
      "sort_order": 1
    },
    {
      "code": "USD",
      "name": "US Dollar",
      "description": "United States Dollar",
      "user_defined_1": null,
      "user_defined_2": null,
      "user_defined_3": null,
      "sort_order": 2
    }
  ],
  "meta": {
    "total": 15,
    "code_class": "Currency",
    "last_synced": "2024-01-15T14:30:30Z",
    "timestamp": "2024-01-15T14:30:30Z"
  }
}

Get Branch Statuses

Retrieve branch status codes (Branch Status - cdCls: 02).

GET/api/v1/codes/branch-statuses

Get Branch Statuses

Retrieve branch operational status codes.

Authentication

Get Sale Statuses

Retrieve sale status codes (Sale Status - cdCls: 06).

GET/api/v1/codes/sale-statuses

Get Sale Statuses

Retrieve sale transaction status codes.

Authentication

Get Purchase Statuses

Retrieve purchase status codes (Purchase Status - cdCls: 12).

GET/api/v1/codes/purchase-statuses

Get Purchase Statuses

Retrieve purchase transaction status codes.

Authentication

Get Stock I/O Types

Retrieve stock input/output type codes (Stock I/O Type - cdCls: 07).

GET/api/v1/codes/stock-io-types

Get Stock I/O Types

Retrieve stock movement type codes (stock in, stock out, adjustment).

Authentication

Get Transaction Types

Retrieve transaction type codes (Transaction Type - cdCls: 08).

GET/api/v1/codes/transaction-types

Get Transaction Types

Retrieve transaction category codes.

Authentication

Get Import Item Statuses

Retrieve import item status codes (Import Item Status - cdCls: 10).

GET/api/v1/codes/import-item-statuses

Get Import Item Statuses

Retrieve import item status codes.

Authentication

Get Refund Reasons

Retrieve refund reason codes (Refund Reason - cdCls: 11).

GET/api/v1/codes/refund-reasons

Get Refund Reasons

Retrieve refund reason codes for credit notes and returns.

Authentication

Get Inventory Adjustment Reasons

Retrieve inventory adjustment reason codes (Reason of Inventory Adjustment - cdCls: 13).

GET/api/v1/codes/inventory-adjustment-reasons

Get Inventory Adjustment Reasons

Retrieve reason codes for stock adjustments.

Authentication

Get Banks

Retrieve bank codes (Bank - cdCls: 14).

GET/api/v1/codes/banks

Get Banks

Retrieve bank codes for payment processing.

Authentication

Get Sales Receipt Types

Retrieve sales receipt type codes (Sales Receipt Type - cdCls: 15).

GET/api/v1/codes/sales-receipt-types

Get Sales Receipt Types

Retrieve receipt type codes for sales transactions.

Authentication

Get Purchase Receipt Types

Retrieve purchase receipt type codes (Purchase Receipt Type - cdCls: 16).

GET/api/v1/codes/purchase-receipt-types

Get Purchase Receipt Types

Retrieve receipt type codes for purchase transactions.

Authentication

Get Tax Offices

Retrieve tax office codes (Tax Office - cdCls: 17).

GET/api/v1/codes/tax-offices

Get Tax Offices

Retrieve KRA tax office identifier codes.

Authentication

Get Locales

Retrieve locale codes (LOCALE - cdCls: 18).

GET/api/v1/codes/locales

Get Locales

Retrieve locale/language codes.

Authentication

Get Item Classes for Select Dropdown

Retrieve item classification codes formatted for select dropdowns.

GET/api/v1/codes/item-classes/select

Get Item Classes (Select Format)

Retrieve item classification codes formatted for UI select dropdowns.

Authentication
Parameters
search
string · query

Search term to filter results

Response

Status: 200 OK

{
  "status": "success",
  "data": [
    {
      "value": "1",
      "label": "1 - Raw Material",
      "code": "1",
      "name": "Raw Material"
    },
    {
      "value": "2",
      "label": "2 - Finished Product",
      "code": "2",
      "name": "Finished Product"
    },
    {
      "value": "3",
      "label": "3 - Service",
      "code": "3",
      "name": "Service"
    }
  ],
  "meta": {
    "total": 3,
    "search": null,
    "timestamp": "2024-01-15T14:30:30Z"
  }
}

Code Classification Reference

cdClsNameDescriptionEndpoint
02Branch StatusBranch operational status/codes/branch-statuses
03Payment TypePayment method types/codes/payment-types
04Taxation TypeTax classification/codes/tax-types
05CountryCountry codes/codes/countries
06Sale StatusSales transaction status/codes/sale-statuses
07Stock I/O TypeStock movement types/codes/stock-io-types
08Transaction TypeTransaction categories/codes/transaction-types
09Item TypeItem classifications/codes/item-types
10Quantity UnitMeasurement units/codes/quantity-units
11CurrencyCurrency codes/codes/currencies
12Purchase StatusPurchase transaction status/codes/purchase-statuses
13Inventory Adjustment ReasonStock adjustment reasons/codes/inventory-adjustment-reasons
14BankBank codes/codes/banks
15Sales Receipt TypeReceipt type for sales/codes/sales-receipt-types
16Purchase Receipt TypeReceipt type for purchases/codes/purchase-receipt-types
17Tax OfficeTax office identifiers/codes/tax-offices
18LOCALELocale/language codes/codes/locales

Code Examples

JavaScript

const axios = require('axios');
 
const apiKey = process.env.CTAX_API_KEY;
const baseURL = 'https://c-tax.1809ltd.co.ke/api/v1';
 
// Sync codes from VSCU
const syncData = {
  bhf_id: '00',
  last_req_dt: '20180520000000'
};
 
const response = await axios.post(`${baseURL}/codes/sync`, syncData, {
  headers: { Authorization: `Bearer ${apiKey}` }
});
 
console.log(`Synced ${response.data.data.synced_classes} classes`);
 
// Get payment types
const paymentTypes = await axios.get(`${baseURL}/codes/payment-types`, {
  headers: { Authorization: `Bearer ${apiKey}` }
});
 
paymentTypes.data.data.forEach(type => {
  console.log(`${type.code}: ${type.name}`);
});
 
// Get item classes for dropdown
const itemClasses = await axios.get(`${baseURL}/codes/item-classes/select`, {
  params: { search: 'product' },
  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',
    ],
]);
 
// Sync codes
$data = [
    'bhf_id' => '00',
    'last_req_dt' => '20180520000000',
];
 
$response = $client->post('codes/sync', ['json' => $data]);
$result = json_decode($response->getBody(), true);
echo "Synced {$result['data']['synced_classes']} classes";
 
// Get tax types
$response = $client->get('codes/tax-types');
$taxTypes = json_decode($response->getBody(), true);
 
foreach ($taxTypes['data'] as $type) {
    echo "{$type['code']}: {$type['name']}\n";
}

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}'}
 
# Sync codes
response = requests.post(
    f'{base_url}/codes/sync',
    json={'bhf_id': '00', 'last_req_dt': '20180520000000'},
    headers=headers
)
print(f"Synced {response.json()['data']['synced_classes']} classes")
 
# Get tax types
tax_types = requests.get(f'{base_url}/codes/tax-types', headers=headers)
for t in tax_types.json()['data']:
    print(f"{t['code']}: {t['name']}")

Best Practices

  1. Sync Regularly - Sync codes periodically to ensure data is up-to-date
  2. Cache Locally - Code data changes infrequently, cache it client-side
  3. Handle Missing Codes - Always check for 404 responses and prompt users to sync
  4. Use Specific Endpoints - Prefer specific endpoints (e.g., /tax-types) over fetching all codes
  5. Monitor Sync Status - Check last_synced_at timestamps to track data freshness
  6. Error Handling - Implement proper error handling for VSCU connectivity issues
Last updated on
Insurances API