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

Notices API

Manage notifications and announcements from the KRA eTIMS/VSCU system.

Overview

The Notices API allows you to retrieve and manage notifications from KRA, including system maintenance announcements, policy updates, and compliance alerts.

List Notices

Get all notices for a branch.

GET/api/v1/notices

List Notices

Retrieve all notices for a branch with optional filtering by read status.

Authentication
Parameters
bhf_id*
string · query

Branch identifier

is_read
boolean · query

Filter by read status

per_page
number · query

Results per page (max 100, default 20)

Response

Status: 200 OK

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "noticeNo": "NOT-2024-001",
      "title": "System Maintenance Notice",
      "content": "VSCU system will undergo maintenance...",
      "dtlUrl": "https://etims.kra.go.ke/notices/123",
      "regrDt": "2024-01-15T10:00:00Z",
      "noticeType": "01",
      "is_read": false,
      "read_at": null
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 45,
    "last_page": 3,
    "timestamp": "2024-01-15T14:30:00Z"
  }
}

Sync Notices

Fetch new notices from KRA eTIMS/VSCU.

POST/api/v1/notices/sync

Sync Notices

Fetch new notices from KRA eTIMS/VSCU system and store them locally.

Authentication
Request BodyJSON

Field Descriptions

FieldTypeRequiredDescription
bhf_idstringYesBranch identifier
last_req_dtstringNoLast request date (YYYYMMDDHHMMSS format, default: 20180520000000)

Response

Status: 200 OK

{
  "status": "success",
  "message": "Notices synced successfully",
  "data": {
    "synced": 3
  }
}

Get Notice Details

Retrieve a specific notice.

GET/api/v1/notices/{id}

Get Notice Details

Retrieve detailed information about a specific notice.

Authentication
Parameters
id*
number · path

Notice ID

Response

Status: 200 OK

{
  "status": "success",
  "data": {
    "id": 1,
    "noticeNo": "NOT-2024-001",
    "title": "System Maintenance Notice",
    "content": "VSCU system will undergo maintenance on January 20, 2024 from 2:00 AM to 6:00 AM EAT...",
    "dtlUrl": "https://etims.kra.go.ke/notices/123",
    "regrDt": "2024-01-15T10:00:00Z",
    "noticeType": "01",
    "is_read": false,
    "read_at": null,
    "raw_data": {...}
  }
}

Mark Notice as Read

Mark a notice as read.

POST/api/v1/notices/{id}/read

Mark Notice as Read

Mark a specific notice as read.

Authentication
Parameters
id*
number · path

Notice ID

Request BodyJSON

Response

Status: 200 OK

{
  "status": "success",
  "message": "Notice marked as read",
  "data": {
    "id": 1,
    "is_read": true,
    "read_at": "2024-01-15T14:30:00Z"
  }
}

Get Unread Count

Get count of unread notices.

GET/api/v1/notices/unread/count

Get Unread Count

Get the count of unread notices for a branch or all branches.

Authentication
Parameters
bhf_id
string · query

Filter by specific branch (omit for all branches)

Response

Status: 200 OK

{
  "status": "success",
  "data": {
    "unread_count": 3
  }
}

Notice Types

CodeDescription
01System Maintenance
02Policy Update
03Compliance Alert
04General Information

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 notices from VSCU
const syncResponse = await axios.post(`${baseURL}/notices/sync`, {
  bhf_id: '00',
  last_req_dt: '20240101000000'
}, {
  headers: { Authorization: `Bearer ${apiKey}` }
});
 
console.log(`Synced ${syncResponse.data.data.synced} notices`);
 
// Get unread count
const countResponse = await axios.get(`${baseURL}/notices/unread/count?bhf_id=00`, {
  headers: { Authorization: `Bearer ${apiKey}` }
});
 
console.log(`Unread notices: ${countResponse.data.data.unread_count}`);
 
// Mark as read
await axios.post(`${baseURL}/notices/${noticeId}/read`, {}, {
  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 notices from VSCU
$response = $client->post('notices/sync', [
    'json' => [
        'bhf_id' => '00',
        'last_req_dt' => '20240101000000',
    ],
]);
 
$result = json_decode($response->getBody(), true);
echo "Synced {$result['data']['synced']} notices\n";
 
// Get unread count
$count = $client->get('notices/unread/count?bhf_id=00');
$countData = json_decode($count->getBody(), true);
echo "Unread: {$countData['data']['unread_count']}\n";
 
// Mark as read
$client->post('notices/1/read');

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 notices
response = requests.post(
    f'{base_url}/notices/sync',
    json={'bhf_id': '00', 'last_req_dt': '20240101000000'},
    headers=headers
)
print(f"Synced {response.json()['data']['synced']} notices")
 
# Get unread count
count = requests.get(
    f'{base_url}/notices/unread/count?bhf_id=00',
    headers=headers
)
print(f"Unread: {count.json()['data']['unread_count']}")
 
# Mark as read
requests.post(f'{base_url}/notices/1/read', headers=headers)

Best Practices

  1. Regular Syncing - Sync notices daily or on application startup
  2. User Notifications - Alert users about unread notices
  3. Store Last Sync Date - Track last sync to avoid duplicate fetches
  4. Mark as Read - Mark notices as read after user views them
  5. Display Prominently - Show important notices in dashboard
Last updated on
WebhooksInsurances API