Salami Gateway

API Documentation
Getting Started
Payments
SMS & Messaging
KRA Portal
eTIMS (OSCU)
SDK Reference
Account & Security
External Links
Back to Dashboard

KRA Checkers API

The Checkers API provides read-only access to 13 KRA validation and lookup services. Validate PINs, check tax compliance, verify invoices, look up customs declarations, and query exemption statuses.

Table of Contents

  1. Overview
  2. PIN Validation
  3. PIN by ID Number
  4. Tax Obligations
  5. TCC Validation
  6. Invoice Checker
  7. Customs Declaration
  8. Income Tax Exemption
  9. VAT Exemption
  10. Import Certificate by Number
  11. Import Certificate by PIN
  12. Excise License by PIN
  13. Excise License by Number
  14. Tax Service Office
  15. Test Data

Overview

Required Scope

Scope Description
kra:checkers Access all 13 checker endpoints

Endpoint Summary

Method Endpoint KRA Path Description
POST /api/kra/checkers/pin /checker/v1/pinbypin Validate a KRA PIN
POST /api/kra/checkers/pin-by-id /checker/v1/pinbyid Look up PIN by ID number
POST /api/kra/checkers/tax-obligations /checker/v1/obligations Get taxpayer obligations
POST /api/kra/checkers/tcc /v1/kra-tcc/validate Validate a TCC
POST /api/kra/checkers/invoice /checker/v1/invoice Verify an eTIMS invoice
POST /api/kra/checkers/declaration /checker/v1/simple/declaration Check customs declaration
POST /api/kra/checkers/it-exemption /checker/v1/itexemption Check IT exemption status
POST /api/kra/checkers/vat-exemption /checker/v1/vatexemption Check VAT exemption status
POST /api/kra/checkers/import-cert-number /checker/v1/importcert/bynumber Look up import cert by number
POST /api/kra/checkers/import-cert-pin /checker/v1/importcert/bypin Look up import certs by PIN
POST /api/kra/checkers/excise-pin /checker/v1/exciselicense/bypin Look up excise license by PIN
POST /api/kra/checkers/excise-number /checker/v1/exciselicense/bynumber Look up excise license by number
POST /api/kra/checkers/tax-service-office /checker/v1/station Get taxpayer's KRA station

PIN Validation

Validate a KRA PIN and retrieve the taxpayer's registered name and status.

Endpoint: POST /api/kra/checkers/pin

Required Scope: kra:checkers

Request Body:

Field Type Required Description
KRAPIN string Yes KRA PIN to validate (format: A000000000B)

Request:

curl -X POST \
  https://yourtenant.salami.dgl.co.ke/api/kra/checkers/pin \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "KRAPIN": "P051234567A"
  }'

Success Response:

{
  "success": true,
  "data": {
    "TaxpayerName": "JOHN DOE SMITH",
    "Status": "Active",
    "PIN": "P051234567A",
    "StationName": "NAIROBI",
    "TaxpayerType": "Individual"
  }
}

Error Response (invalid PIN):

{
  "success": false,
  "message": "KRA API error: PIN not found",
  "error": "kra_error"
}

PIN by ID Number

Look up a KRA PIN using an identification document number (National ID, Passport, etc.).

Endpoint: POST /api/kra/checkers/pin-by-id

Required Scope: kra:checkers

Request Body:

Field Type Required Description
TaxpayerID string Yes ID document number
TaxpayerType string Yes Type of ID document

Taxpayer Type Codes:

Code Description
1 National ID
2 Passport
3 Service ID (Military)
4 Alien ID

Request:

curl -X POST \
  https://yourtenant.salami.dgl.co.ke/api/kra/checkers/pin-by-id \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "TaxpayerID": "12345678",
    "TaxpayerType": "1"
  }'

Response:

{
  "success": true,
  "data": {
    "KRAPIN": "A001234567B",
    "TaxpayerName": "JOHN DOE SMITH",
    "Status": "Active",
    "IdentificationType": "National ID",
    "IdentificationNumber": "12345678"
  }
}

Tax Obligations

Retrieve a taxpayer's registered tax obligations (VAT, Income Tax, PAYE, etc.).

Endpoint: POST /api/kra/checkers/tax-obligations

Required Scope: kra:checkers

Request Body:

Field Type Required Description
KRAPIN string Yes KRA PIN to query

Request:

curl -X POST \
  https://yourtenant.salami.dgl.co.ke/api/kra/checkers/tax-obligations \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "KRAPIN": "P051234567A"
  }'

Response:

{
  "success": true,
  "data": {
    "KRAPIN": "P051234567A",
    "TaxpayerName": "ACME LIMITED",
    "Obligations": [
      {
        "ObligationCode": "IT",
        "ObligationName": "Income Tax - Resident",
        "Status": "Active",
        "EffectiveFrom": "2020-01-15"
      },
      {
        "ObligationCode": "VAT",
        "ObligationName": "Value Added Tax",
        "Status": "Active",
        "EffectiveFrom": "2020-06-01"
      },
      {
        "ObligationCode": "PAYE",
        "ObligationName": "Pay As You Earn",
        "Status": "Active",
        "EffectiveFrom": "2020-01-15"
      }
    ]
  }
}

TCC Validation

Validate a Tax Compliance Certificate (TCC) number against a KRA PIN.

Endpoint: POST /api/kra/checkers/tcc

Required Scope: kra:checkers

Request Body:

Field Type Required Description
kraPIN string Yes KRA PIN of the TCC holder
tccNumber string Yes TCC certificate number

Request:

curl -X POST \
  https://yourtenant.salami.dgl.co.ke/api/kra/checkers/tcc \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "kraPIN": "P051234567A",
    "tccNumber": "TCC/2026/0001234"
  }'

Response:

{
  "success": true,
  "data": {
    "PIN": "P051234567A",
    "TaxpayerName": "ACME LIMITED",
    "TCCNumber": "TCC/2026/0001234",
    "Status": "Valid",
    "IssueDate": "2026-01-15",
    "ExpiryDate": "2026-12-31",
    "Purpose": "General Business"
  }
}

Invoice Checker

Verify an eTIMS/TIMS invoice number and date.

Endpoint: POST /api/kra/checkers/invoice

Required Scope: kra:checkers

Request Body:

Field Type Required Description
invoiceNumber string Yes The invoice/CU number to verify
invoiceDate string Yes Invoice date (YYYY-MM-DD)

Request:

curl -X POST \
  https://yourtenant.salami.dgl.co.ke/api/kra/checkers/invoice \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "invoiceNumber": "CU2026001-00001",
    "invoiceDate": "2026-03-15"
  }'

Response:

{
  "success": true,
  "data": {
    "InvoiceNumber": "CU2026001-00001",
    "InvoiceDate": "2026-03-15",
    "SellerPIN": "P051234567A",
    "SellerName": "ACME LIMITED",
    "BuyerPIN": "A009876543B",
    "TotalAmount": 11600.00,
    "TaxAmount": 1600.00,
    "Status": "Valid",
    "DeviceSerial": "DVC2026001"
  }
}

Customs Declaration

Check the status of a customs declaration. See KRA Customs for full details.

Endpoint: POST /api/kra/checkers/declaration

Required Scope: kra:checkers

Request Body:

Field Type Required Description
DeclarationNo string Yes Customs declaration number

Request:

curl -X POST \
  https://yourtenant.salami.dgl.co.ke/api/kra/checkers/declaration \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "DeclarationNo": "2026ICD001234"
  }'

Response:

{
  "success": true,
  "data": {
    "DeclarationNo": "2026ICD001234",
    "Status": "Released",
    "DeclarationType": "Import",
    "ImporterPIN": "P051234567A",
    "ImporterName": "ACME LIMITED",
    "PortOfEntry": "Mombasa",
    "DeclarationDate": "2026-03-10",
    "AssessedDuty": 125000.00,
    "PaidAmount": 125000.00
  }
}

Income Tax Exemption

Check whether a taxpayer has an active income tax (IT) exemption.

Endpoint: POST /api/kra/checkers/it-exemption

Required Scope: kra:checkers

Request Body:

Field Type Required Description
KRAPIN string Yes KRA PIN to check

Request:

curl -X POST \
  https://yourtenant.salami.dgl.co.ke/api/kra/checkers/it-exemption \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "KRAPIN": "P051234567A"
  }'

Response:

{
  "success": true,
  "data": {
    "KRAPIN": "P051234567A",
    "TaxpayerName": "CHARITY ORGANIZATION LTD",
    "ITExemptionStatus": "Exempt",
    "ExemptionNumber": "ITX/2025/00456",
    "EffectiveFrom": "2025-01-01",
    "EffectiveTo": "2027-12-31",
    "ExemptionType": "Charitable Organization"
  }
}

VAT Exemption

Check whether a taxpayer has an active VAT exemption.

Endpoint: POST /api/kra/checkers/vat-exemption

Required Scope: kra:checkers

Request Body:

Field Type Required Description
KRAPIN string Yes KRA PIN to check

Request:

curl -X POST \
  https://yourtenant.salami.dgl.co.ke/api/kra/checkers/vat-exemption \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "KRAPIN": "P051234567A"
  }'

Response:

{
  "success": true,
  "data": {
    "KRAPIN": "P051234567A",
    "TaxpayerName": "DIPLOMATIC MISSION",
    "VATExemptionStatus": "Exempt",
    "ExemptionNumber": "VATX/2025/00789",
    "EffectiveFrom": "2025-01-01",
    "EffectiveTo": "2027-12-31",
    "ExemptionType": "Diplomatic Exemption"
  }
}

Import Certificate by Number

Look up an import certificate using its certificate number.

Endpoint: POST /api/kra/checkers/import-cert-number

Required Scope: kra:checkers

Request Body:

Field Type Required Description
CertificateNumber string Yes Import certificate number

Request:

curl -X POST \
  https://yourtenant.salami.dgl.co.ke/api/kra/checkers/import-cert-number \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "CertificateNumber": "IMP/2026/001234"
  }'

Response:

{
  "success": true,
  "data": {
    "CertificateNumber": "IMP/2026/001234",
    "HolderPIN": "P051234567A",
    "HolderName": "ACME LIMITED",
    "Status": "Valid",
    "IssueDate": "2026-02-01",
    "ExpiryDate": "2026-08-01",
    "Description": "Raw Materials Import",
    "ItemDescription": "Steel Sheets HS 7208",
    "Quantity": "500 MT"
  }
}

Import Certificate by PIN

Look up all import certificates associated with a KRA PIN.

Endpoint: POST /api/kra/checkers/import-cert-pin

Required Scope: kra:checkers

Request Body:

Field Type Required Description
KRAPIN string Yes KRA PIN of the certificate holder

Request:

curl -X POST \
  https://yourtenant.salami.dgl.co.ke/api/kra/checkers/import-cert-pin \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "KRAPIN": "P051234567A"
  }'

Response:

{
  "success": true,
  "data": {
    "KRAPIN": "P051234567A",
    "TaxpayerName": "ACME LIMITED",
    "Certificates": [
      {
        "CertificateNumber": "IMP/2026/001234",
        "Status": "Valid",
        "IssueDate": "2026-02-01",
        "ExpiryDate": "2026-08-01"
      },
      {
        "CertificateNumber": "IMP/2025/009876",
        "Status": "Expired",
        "IssueDate": "2025-03-01",
        "ExpiryDate": "2025-09-01"
      }
    ]
  }
}

Excise License by PIN

Look up all excise licenses associated with a KRA PIN.

Endpoint: POST /api/kra/checkers/excise-pin

Required Scope: kra:checkers

Request Body:

Field Type Required Description
KRAPIN string Yes KRA PIN of the license holder

Request:

curl -X POST \
  https://yourtenant.salami.dgl.co.ke/api/kra/checkers/excise-pin \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "KRAPIN": "P051234567A"
  }'

Response:

{
  "success": true,
  "data": {
    "KRAPIN": "P051234567A",
    "TaxpayerName": "BEVERAGES KENYA LTD",
    "Licenses": [
      {
        "LicenseNumber": "EXC/2026/00567",
        "LicenseType": "Excise Manufacturer",
        "Status": "Active",
        "IssueDate": "2026-01-01",
        "ExpiryDate": "2026-12-31",
        "Product": "Alcoholic Beverages"
      }
    ]
  }
}

Excise License by Number

Look up a specific excise license by its certificate number.

Endpoint: POST /api/kra/checkers/excise-number

Required Scope: kra:checkers

Request Body:

Field Type Required Description
CertificateNumber string Yes Excise license certificate number

Request:

curl -X POST \
  https://yourtenant.salami.dgl.co.ke/api/kra/checkers/excise-number \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "CertificateNumber": "EXC/2026/00567"
  }'

Response:

{
  "success": true,
  "data": {
    "CertificateNumber": "EXC/2026/00567",
    "HolderPIN": "P051234567A",
    "HolderName": "BEVERAGES KENYA LTD",
    "LicenseType": "Excise Manufacturer",
    "Status": "Active",
    "IssueDate": "2026-01-01",
    "ExpiryDate": "2026-12-31",
    "Location": "Nairobi Industrial Area",
    "Product": "Alcoholic Beverages"
  }
}

Tax Service Office

Retrieve the KRA station (tax service office) assigned to a taxpayer.

Endpoint: POST /api/kra/checkers/tax-service-office

Required Scope: kra:checkers

Request Body:

Field Type Required Description
KRAPIN string Yes KRA PIN to query

Request:

curl -X POST \
  https://yourtenant.salami.dgl.co.ke/api/kra/checkers/tax-service-office \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "KRAPIN": "P051234567A"
  }'

Response:

{
  "success": true,
  "data": {
    "KRAPIN": "P051234567A",
    "TaxpayerName": "ACME LIMITED",
    "StationCode": "NRB01",
    "StationName": "Nairobi Station",
    "Region": "Nairobi",
    "Address": "Times Tower, Haile Selassie Avenue",
    "Telephone": "+254 20 2814540"
  }
}

Test Data

Use these values when testing against the KRA sandbox environment:

Valid Sandbox PINs

PIN Name Type
P051234567A Test Individual Individual
P051111111A Test Company Ltd Company
A001234567B Test Business Non-Individual

Valid Sandbox ID Numbers

ID Number Type Code Type
12345678 1 National ID
AB123456 2 Passport

Valid Sandbox TCC Numbers

TCC Number PIN
TCC/2026/0001234 P051234567A

Valid Sandbox Invoice Numbers

Invoice Number Date
CU2026001-00001 2026-03-15

Valid Sandbox Declaration Numbers

Declaration Number
2026ICD001234

Note: Sandbox responses may contain dummy data. Always validate your integration logic with realistic test scenarios before switching to production.

Status Codes

Code Description
200 Successful lookup
401 Invalid or missing Salami token
403 Token lacks kra:checkers scope
422 Missing required fields
502 KRA server error or timeout

Related Documentation

Back to: KRA Overview | KRA Apps

Need help? Contact us at support@dgl.co.ke
© 2026 Deadan Group Limited. All rights reserved.
⚡ API Explorer
LIVE
// Response will appear here...