eTIMS Invoice Verification API

Verify eTIMS invoices received from suppliers or other businesses. Confirm that an invoice is genuine and registered in the KRA system.

Overview
Verify Invoice
List Verifications
Status Codes

Overview

Required Scopes

Scope	Description
`etims:read`	Verify invoices, list verification history

Endpoint Summary

Method	Endpoint	Description	Scope
`POST`	`/api/etims/verify-invoice`	Verify an eTIMS invoice	`etims:read`
`GET`	`/api/etims/verifications`	List verification history	`etims:read`

Why Verify Invoices?

Invoice verification ensures:

The invoice was genuinely submitted to KRA via eTIMS
The seller's TIN and amounts match KRA records
You are claiming valid input VAT on legitimate invoices
Compliance with KRA's invoice authenticity requirements

Verify Invoice

Verify an eTIMS invoice by its number and date.

Endpoint: POST /api/etims/verify-invoice

Required Scope: etims:read

Request Body:

Field	Type	Required	Description
`invoice_number`	string	Yes	eTIMS invoice or CU number
`invoice_date`	string	Yes	Invoice date (YYYY-MM-DD)
`seller_tin`	string	No	Expected seller TIN (additional verification)

Request:

curl -X POST \
  https://yourtenant.salami.dgl.co.ke/api/etims/verify-invoice \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "invoice_number": "CU2026001-00001",
    "invoice_date": "2026-03-29",
    "seller_tin": "P051234567A"
  }'

Valid Invoice Response:

{
  "success": true,
  "data": {
    "verification_id": 201,
    "invoice_number": "CU2026001-00001",
    "invoice_date": "2026-03-29",
    "is_valid": true,
    "seller_tin": "P051234567A",
    "seller_name": "ACME LIMITED",
    "buyer_tin": "A009876543B",
    "total_amount": 30000.00,
    "total_tax": 4137.93,
    "verification_result": {
      "invoice_exists": true,
      "seller_match": true,
      "date_match": true,
      "status": "VERIFIED"
    },
    "verified_at": "2026-03-29T17:10:00Z"
  },
  "message": "Invoice verified successfully - invoice is valid"
}

Invalid Invoice Response:

{
  "success": true,
  "data": {
    "verification_id": 202,
    "invoice_number": "FAKE-INV-001",
    "invoice_date": "2026-03-29",
    "is_valid": false,
    "seller_tin": null,
    "seller_name": null,
    "buyer_tin": null,
    "total_amount": 0,
    "total_tax": 0,
    "verification_result": {
      "invoice_exists": false,
      "seller_match": false,
      "date_match": false,
      "status": "NOT_FOUND"
    },
    "verified_at": "2026-03-29T17:12:00Z"
  },
  "message": "Invoice verification failed - invoice not found in KRA records"
}

Mismatched Seller Response:

{
  "success": true,
  "data": {
    "verification_id": 203,
    "invoice_number": "CU2026001-00001",
    "invoice_date": "2026-03-29",
    "is_valid": false,
    "seller_tin": "P051234567A",
    "seller_name": "ACME LIMITED",
    "buyer_tin": "A009876543B",
    "total_amount": 30000.00,
    "total_tax": 4137.93,
    "verification_result": {
      "invoice_exists": true,
      "seller_match": false,
      "date_match": true,
      "status": "SELLER_MISMATCH",
      "expected_seller": "B005566778C",
      "actual_seller": "P051234567A"
    },
    "verified_at": "2026-03-29T17:15:00Z"
  },
  "message": "Invoice found but seller TIN does not match"
}

Response Fields

Field	Type	Description
`verification_id`	integer	Unique verification record ID
`invoice_number`	string	The invoice number checked
`invoice_date`	string	The date checked
`is_valid`	boolean	Overall validity (`true` = genuine and matching)
`seller_tin`	string/null	Seller's TIN from KRA records
`seller_name`	string/null	Seller's name from KRA records
`buyer_tin`	string/null	Buyer's TIN from KRA records
`total_amount`	number	Invoice total from KRA records
`total_tax`	number	Tax amount from KRA records
`verification_result`	object	Detailed verification breakdown
`verified_at`	string	ISO 8601 verification timestamp

Verification Result Statuses

Status	Description
`VERIFIED`	Invoice exists and all checks pass
`NOT_FOUND`	Invoice does not exist in KRA records
`SELLER_MISMATCH`	Invoice exists but seller TIN does not match
`DATE_MISMATCH`	Invoice exists but date does not match
`CANCELLED`	Invoice exists but has been cancelled

List Verifications

Retrieve your invoice verification history.

Endpoint: GET /api/etims/verifications

Required Scope: etims:read

Query Parameters:

Parameter	Type	Required	Description
`is_valid`	boolean	No	Filter by validity (`true` or `false`)
`seller_tin`	string	No	Filter by seller TIN
`start_date`	string	No	Filter from date
`end_date`	string	No	Filter to date
`page`	integer	No	Page number
`per_page`	integer	No	Results per page

Request:

curl -X GET \
  'https://yourtenant.salami.dgl.co.ke/api/etims/verifications?is_valid=true&start_date=2026-03-01' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Response:

{
  "success": true,
  "data": [
    {
      "id": 201,
      "invoice_number": "CU2026001-00001",
      "invoice_date": "2026-03-29",
      "is_valid": true,
      "seller_tin": "P051234567A",
      "seller_name": "ACME LIMITED",
      "total_amount": 30000.00,
      "total_tax": 4137.93,
      "verified_at": "2026-03-29T17:10:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "per_page": 50,
    "current_page": 1,
    "last_page": 1
  }
}

Status Codes

Code	Description
`200`	Verification completed (check `is_valid` for result)
`401`	Invalid Salami token
`403`	Token lacks `etims:read` scope
`422`	Missing required fields
`502`	KRA eTIMS server error

Best Practices

Verify before claiming VAT -- Always verify supplier invoices before claiming input VAT
Check seller TIN -- Include the expected seller_tin for additional security
Keep verification records -- Verification history serves as an audit trail
Verify promptly -- Verify invoices when received, not at return-filing time
Handle invalid invoices -- Follow up with suppliers if verification fails
Batch verifications -- Verify all purchase invoices for the period before filing returns

Salami Gateway