eTIMS Customers & Suppliers API

Manage customer and supplier records in eTIMS. Maintain a directory of business contacts synced with KRA for invoice and purchase compliance.

Table of Contents

1. Overview
2. Customers
3. Suppliers
4. Status Codes

Overview

Required Scopes

Endpoint Summary

Customers

Create Customer

Register a new customer in the eTIMS system. Customer records are synced with KRA and can be referenced in sales transactions.

Endpoint: POST /api/etims/customers

Required Scope: etims:write

Request Body:

Request:

curl -X POST \
  https://yourtenant.salami.dgl.co.ke/api/etims/customers \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "cust_tin": "A009876543B",
    "cust_nm": "Jane Wanjiku Enterprises",
    "adrs": "P.O. Box 54321, Nairobi",
    "tel_no": "+254712345678",
    "email": "jane@wanjiku.co.ke",
    "use_yn": "Y"
  }'

Response:

{
  "success": true,
  "data": {
    "id": 101,
    "cust_no": "CUST-101",
    "cust_tin": "A009876543B",
    "cust_nm": "Jane Wanjiku Enterprises",
    "adrs": "P.O. Box 54321, Nairobi",
    "tel_no": "+254712345678",
    "email": "jane@wanjiku.co.ke",
    "use_yn": "Y",
    "synced_at": "2026-03-29T16:35:00Z"
  },
  "message": "Customer created and synced with KRA"
}

Get Customer

Endpoint: GET /api/etims/customers/{id}

Required Scope: etims:read

Request:

curl -X GET \
  https://yourtenant.salami.dgl.co.ke/api/etims/customers/101 \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Response:

{
  "success": true,
  "data": {
    "id": 101,
    "cust_no": "CUST-101",
    "cust_tin": "A009876543B",
    "cust_nm": "Jane Wanjiku Enterprises",
    "adrs": "P.O. Box 54321, Nairobi",
    "tel_no": "+254712345678",
    "email": "jane@wanjiku.co.ke",
    "use_yn": "Y",
    "total_purchases": 12,
    "total_amount": 450000.00,
    "created_at": "2026-03-29T16:35:00Z"
  }
}

Update Customer

Endpoint: PUT /api/etims/customers/{id}

Required Scope: etims:write

Request:

curl -X PUT \
  https://yourtenant.salami.dgl.co.ke/api/etims/customers/101 \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "tel_no": "+254723456789",
    "email": "info@wanjiku.co.ke"
  }'

Response:

{
  "success": true,
  "data": {
    "id": 101,
    "cust_tin": "A009876543B",
    "cust_nm": "Jane Wanjiku Enterprises",
    "tel_no": "+254723456789",
    "email": "info@wanjiku.co.ke",
    "updated_at": "2026-03-29T16:40:00Z"
  },
  "message": "Customer updated successfully"
}

List Customers

Endpoint: GET /api/etims/customers

Required Scope: etims:read

Query Parameters:

Request:

curl -X GET \
  'https://yourtenant.salami.dgl.co.ke/api/etims/customers?search=wanjiku' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Response:

{
  "success": true,
  "data": [
    {
      "id": 101,
      "cust_tin": "A009876543B",
      "cust_nm": "Jane Wanjiku Enterprises",
      "tel_no": "+254723456789",
      "use_yn": "Y",
      "created_at": "2026-03-29T16:35:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "per_page": 50,
    "current_page": 1,
    "last_page": 1
  }
}

Suppliers

Create Supplier

Register a new supplier in the eTIMS system. Supplier records are linked to purchase transactions.

Endpoint: POST /api/etims/suppliers

Required Scope: etims:write

Request Body:

Request:

curl -X POST \
  https://yourtenant.salami.dgl.co.ke/api/etims/suppliers \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "spplr_tin": "P051234567B",
    "spplr_nm": "Premium Furniture Suppliers Ltd",
    "adrs": "Industrial Area, Nairobi",
    "tel_no": "+254734567890",
    "email": "sales@premiumfurniture.co.ke",
    "use_yn": "Y"
  }'

Response:

{
  "success": true,
  "data": {
    "id": 12,
    "spplr_tin": "P051234567B",
    "spplr_nm": "Premium Furniture Suppliers Ltd",
    "adrs": "Industrial Area, Nairobi",
    "tel_no": "+254734567890",
    "email": "sales@premiumfurniture.co.ke",
    "use_yn": "Y",
    "synced_at": "2026-03-29T16:45:00Z"
  },
  "message": "Supplier created and synced with KRA"
}

Get Supplier

Endpoint: GET /api/etims/suppliers/{id}

Required Scope: etims:read

Request:

curl -X GET \
  https://yourtenant.salami.dgl.co.ke/api/etims/suppliers/12 \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Response:

{
  "success": true,
  "data": {
    "id": 12,
    "spplr_tin": "P051234567B",
    "spplr_nm": "Premium Furniture Suppliers Ltd",
    "adrs": "Industrial Area, Nairobi",
    "tel_no": "+254734567890",
    "email": "sales@premiumfurniture.co.ke",
    "use_yn": "Y",
    "total_purchases": 8,
    "total_amount": 640000.00,
    "created_at": "2026-03-29T16:45:00Z"
  }
}

List Suppliers

Endpoint: GET /api/etims/suppliers

Required Scope: etims:read

Query Parameters:

Request:

curl -X GET \
  'https://yourtenant.salami.dgl.co.ke/api/etims/suppliers?use_yn=Y' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Response:

{
  "success": true,
  "data": [
    {
      "id": 12,
      "spplr_tin": "P051234567B",
      "spplr_nm": "Premium Furniture Suppliers Ltd",
      "tel_no": "+254734567890",
      "use_yn": "Y",
      "created_at": "2026-03-29T16:45:00Z"
    }
  ],
  "pagination": {
    "total": 8,
    "per_page": 50,
    "current_page": 1,
    "last_page": 1
  }
}

Status Codes

Best Practices

1. Verify TINs -- Use KRA PIN Validation before creating records
2. Unique TINs -- Each supplier TIN must be unique in the system
3. Keep records current -- Update contact details when they change
4. Deactivate vs delete -- Set use_yn: N instead of deleting records
5. Link to transactions -- Reference supplier IDs in purchase submissions

Related Documentation

• eTIMS Sales -- Reference customers in sales
• eTIMS Purchases -- Reference suppliers in purchases
• KRA Checkers -- Validate TINs before registration

Back to: eTIMS Purchases | eTIMS Reverse Invoices