Get up and running with the Ushuru eTIMS API in four steps.

Step 1 | Check Service Health

Verify the API is reachable. This is a public endpoint, no API key required.

GET /api/v1/health

Returns { "success": true, "data": { "status": "ok", ... } } when the API is live.

Step 2 | Initialize Your Device

Create an API key in the Ushuru dashboard, then initialize your OSCU device:

POST /api/v1/initialize
x-api-key: YOUR_API_KEY

{ "deviceSerialNumber": "YOUR_DEVICE_SERIAL" }

Until initialization succeeds, protected endpoints return 503 with a nextStep hint. Check readiness with GET /api/v1/etims-info (isReady: true) or GET /api/v1/status with your API key.

Step 3 | Register an Item

Every item sold must be registered with Kenya Revenue Authority before it can appear on an invoice. Use POST /api/v1/items/service for software, consulting, or any service.

Required fields include itemClsCd (10-digit Kenya Revenue Authority classification code).

Step 4 | Submit a Sale

Call POST /api/v1/sales with { transaction, lineItems } for every transaction. Kenya Revenue Authority returns internalData and receiptSignature, both must be printed on every customer receipt.

Print on every receipt: internalData (26 chars) and receiptSignature (16 chars) are Kenya Revenue Authority compliance requirements.