KRA Tax Returns API

File Turnover Tax (TOT) returns and NIL returns through the KRA developer.go.ke API. These endpoints support basic return filing for small businesses and nil-declaration scenarios.

Table of Contents

1. Overview
2. File TOT Return
3. File NIL Return
4. Obligation Codes
5. Status Codes

Overview

Required Scope

Endpoint Summary

File TOT Return

Submit a Turnover Tax (TOT) return. TOT applies to businesses with annual gross turnover between KES 1 million and KES 50 million.

Endpoint: POST /api/kra/returns/tot

Required Scope: kra:returns

Request Body:

You can submit fields in either flat or nested format. Salami wraps flat fields inside TAXPAYERDETAILS automatically.

Flat Format

{
  "TaxpayerPIN": "P051234567A",
  "Month": "03",
  "Year": "2026",
  "GrossTurnover": 450000.00
}

Nested Format

{
  "TAXPAYERDETAILS": {
    "TaxpayerPIN": "P051234567A",
    "Month": "03",
    "Year": "2026",
    "GrossTurnover": 450000.00
  }
}

Parameter Table

Request:

curl -X POST \
  https://yourtenant.salami.dgl.co.ke/api/kra/returns/tot \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "TaxpayerPIN": "P051234567A",
    "Month": "03",
    "Year": "2026",
    "GrossTurnover": 450000.00
  }'

Success Response:

{
  "success": true,
  "data": {
    "AckNumber": "TOT/ACK/2026/001234",
    "TaxpayerPIN": "P051234567A",
    "Period": "March 2026",
    "GrossTurnover": 450000.00,
    "TaxRate": 3,
    "TaxPayable": 13500.00,
    "PRN": "KRA2026000567890",
    "DueDate": "2026-04-20",
    "Status": "Filed"
  },
  "message": "TOT return filed successfully"
}

Response Fields

TOT Rate

Note: TOT rate is 3% as of January 2024. Rates are subject to KRA changes.

File NIL Return

Submit a NIL return when there is no income or activity to report for a given period. NIL returns can be filed for any obligation.

Endpoint: POST /api/kra/returns/nil

Required Scope: kra:returns

Request Body:

Flat Format

{
  "TaxpayerPIN": "P051234567A",
  "ObligationCode": "1",
  "Month": "03",
  "Year": "2026"
}

Nested Format

{
  "TAXPAYERDETAILS": {
    "TaxpayerPIN": "P051234567A",
    "ObligationCode": "1",
    "Month": "03",
    "Year": "2026"
  }
}

Parameter Table

Request:

curl -X POST \
  https://yourtenant.salami.dgl.co.ke/api/kra/returns/nil \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "TaxpayerPIN": "P051234567A",
    "ObligationCode": "1",
    "Month": "03",
    "Year": "2026"
  }'

Success Response:

{
  "success": true,
  "data": {
    "AckNumber": "NIL/ACK/2026/005678",
    "TaxpayerPIN": "P051234567A",
    "ObligationCode": "1",
    "ObligationName": "Income Tax - Resident Individual",
    "Period": "March 2026",
    "Status": "Filed",
    "FiledAt": "2026-03-29T12:30:00Z"
  },
  "message": "NIL return filed successfully"
}

Error Response (already filed):

{
  "success": false,
  "message": "KRA API error: Return for this period has already been filed",
  "error": "kra_error"
}

Response Fields

Obligation Codes

Use these codes with the NIL return endpoint:

Obligation Applicability

Validation Errors

TOT Return

{
  "success": false,
  "message": "Required fields missing: TAXPAYERDETAILS.TaxpayerPIN, TAXPAYERDETAILS.GrossTurnover",
  "error": "validation_error"
}

NIL Return

{
  "success": false,
  "message": "Required fields missing: TAXPAYERDETAILS.ObligationCode",
  "error": "validation_error"
}

Status Codes

Best Practices

1. File on time -- Monthly returns are due by the 20th of the following month
2. File NIL when inactive -- Always file NIL returns even when there is no activity to report
3. Verify obligation status -- Use Tax Obligations checker to confirm which obligations are active
4. Store acknowledgement numbers -- Save the AckNumber for your records
5. Avoid duplicate filings -- Check if a return for the period has already been filed
6. Zero vs NIL -- Use TOT endpoint with GrossTurnover: 0 for zero-turnover months; use NIL for no-activity months

Related Documentation

• KRA Overview
• KRA Checkers -- Verify obligations before filing
• KRA Payments -- Generate PRNs for tax remittance
• KRA Compliance -- TCC applications (require returns to be filed)

Back to: KRA Overview | KRA Payments