Skip to main content
This guide explains how you act as the third-party integrator: your platform syncs data between your customers’ accounting tools (e.g. QuickBooks, Xero) and KRA eTIMS via OSCU (or VSCU). References you have:

​
0. Integration Token Is Required (OSCU and VSCU)

If the eTIMS portal requires an Integration Token to submit a Service Request for both OSCU and VSCU, you cannot complete the form without it. The token is not something you create yourself—it is issued by KRA after you become a certified integrator.

​
How to get your Integration Tokenhttps://www.kra.go.ke/images/publications/OSCU_VSCU_Step-by-Step_Guide-on-how-to-sign-up.pdf

  1. Apply for certification with KRA
    You must be certified before you (or your customers) can use your token on the Service Request form.
    • Official page: eTIMS System to System Integration - KRA
    • Process: Development → Testing (sandbox) → Vetting → Certification.
    • Who can apply: Taxpayers who self-integrate or third-party software developers (integrators) who integrate on behalf of others. Both must be certified before going live.
  2. Submit the eTIMS Bio Data Form
    This is the formal application for certification.
  3. What the Bio Data Form typically requires
    • Company/business name, TCC (Tax Compliance Certificate).
    • Product description (your TIS / integration software).
    • Details of at least three qualified technical staff (CVs, terms of employment).
    • Read-only optical disk (or as specified) with your TIS integration software and documentation.
      For third-party vendors only: Business registration (e.g. CR12), business permit, ID copies of directors/partners, experience in similar software, notarized declaration (e.g. not insolvent/receivership).
  4. After KRA approves your certification
    KRA will issue your Integration Token. You (and your customers, when they choose you as integrator) then use this token in the Integration Token field on the Service Request form and click Verify to proceed.
  5. Sandbox vs production
    Ask KRA eTIMS Operations explicitly: “We are applying as a third-party integrator. The portal requires an Integration Token to submit a Service Request. How do we obtain the Integration Token for sandbox testing and for production?” They may give you a sandbox token first so you can test before full production certification.

​
0.1 Development keys: what to use to build and demonstrate before KRA gives you the customer token

There are no public “developer” or “test” Integration Tokens published by KRA. The specs and step-by-step guide do not include a shared sandbox token. To develop first and show KRA your integration before you have the final token that customers will use, you must get development/sandbox access from KRA. What to do:
  1. Contact KRA eTIMS and request a sandbox/development Integration Token Ask clearly, for example: “We are applying to become a certified third-party integrator for eTIMS (OSCU/VSCU). To develop and test our integration we need to submit a Service Request on the sandbox portal, but the form requires an Integration Token. Please advise how we can obtain a sandbox or development Integration Token so we can build, test, and demonstrate our integration to KRA before full certification and before receiving the production token for our customers.”
  2. Possible outcomes (KRA will confirm)
    They may issue a provisional/sandbox-only token, or ask you to submit the Bio Data Form first and then provide a sandbox token as part of certification. Follow whatever KRA eTIMS Operations instructs.
  3. What you can do without a token (while waiting)
    Implement against the Technical Spec v2.0 (request/response formats, sequence, error handling), point your client at https://etims-api-sbx.kra.go.ke with placeholder credentials, prepare the Bio Data Form and supporting docs, and document your integration for KRA.
Summary (Section 0): For both OSCU and VSCU, if the portal mandates the Integration Token, the only way to get it is to apply for certification using the eTIMS Bio Data Form. To get development keys to build and demonstrate before the final customer token, contact timsupport@kra.go.ke and ask for a sandbox/development Integration Token or the process for the certification development phase.

​
1. OSCU vs VSCU (Why OSCU for You)

Conclusion: Use the OSCU path. Your system is the TIS; KRA’s OSCU is at https://etims-api-sbx.kra.go.ke (sandbox) and https://etims-api.kra.go.ke (production).

​
2. High-Level Flow (You as Integrator)

  1. Customer onboarding
    • Customer (or you on their behalf) signs up on eTIMS sandbox/production and submits a Service Request for OSCU (not VSCU).
    • After approval, they (or you) run device initialization with PIN, branch office ID, and equipment info → KRA returns a communication key.
    • You store per connection: KRA PIN, branch office ID, communication key (and any serial/cert the spec requires). No “Integration Token” is involved.
  2. Your API
    • For each customer you call KRA’s OSCU endpoints with their credentials.
    • You implement the mandatory sequence (initialization → basic data → branch → items → sales/stock/purchases) as in the step-by-step guide.
  3. Two-way sync
    • To eTIMS: Send sales, invoices, credit notes, items, stock in/out (from accounting tool → your API → KRA).
    • From eTIMS: Get purchases, item list, PIN list, notices, etc. (KRA → your API → accounting tool).

​
3. Where Credentials Come From (No Integration Token)

  • KRA PIN – The business’s existing KRA PIN (used for eTIMS sign-up).
  • Branch office ID – From KRA after OSCU approval (often 00 for first branch, then 01, 02…; exact values in portal or step-by-step guide).
  • Serial / equipment info – As per the Technical Spec: either provided in the Service Request or assigned by KRA; used in the initialization call.
  • Communication key – Returned by KRA when you call the initialization endpoint (/selectInitOsdcInfo or as in the spec). You must store it and use it for subsequent authenticated calls.
If the portal requires an Integration Token for both OSCU and VSCU, you must first become a certified integrator (Section 0). KRA issues your token after you submit the eTIMS Bio Data Form and are approved. Once you have the token, you (or your customers) use it on the Service Request form to get the request approved; then you use PIN, branch office ID, and the communication key from the initialization API for actual API calls.

​
4. Mandatory Order of Operations (From the Step-by-Step Guide)

The OSCU/VSCU Step-by-Step Guide and the Technical Spec require this sequence. Later steps depend on earlier ones. So for your three aims:
  • ① Manage inventory → Implement Item management (send item info, get item list) and Stock management (send stock in/out, send stock inventory), after initialization and branch info.
  • ② Create a sale; create a credit note → Implement Sales management (sales transaction + sales invoice); then the credit note / cancel / refund services from the Technical Spec.
  • ③ Get purchases (and other KRA-supported things) → Implement Purchase transaction management (get purchase transactions, send confirmation) and Basic data (get codes, PIN list, notices, etc.).

​
5. Endpoints and Environments

From the step-by-step guide:
  • Sandbox base URL: https://etims-api-sbx.kra.go.ke
  • Production base URL: https://etims-api.kra.go.ke
Example for device activation (Technical Spec gives the exact path, often /selectInitOsdcInfo):
  • Sandbox: https://etims-api-sbx.kra.go.ke/selectInitOsdcInfo
All other service paths (item, sales, stock, purchase, etc.) are in the TIS for OSCU/VSCU Technical Specifications v2.0 PDF: request/response format, URL path, and authentication (e.g. how to send the communication key).

​
6. Practical Implementation Checklist

  1. Read the Technical Spec v2.0
    • Section 2.2 (and related): initialization, main configurations, technical policies.
    • Exact URL paths and request bodies for: init, basic data, branch, item, sales, credit note/cancel, purchase, stock.
  2. Get your Integration Token (if portal requires it)
  3. Onboard one test business (sandbox)
    • Sign up at https://etims-sbx.kra.go.ke with a test PIN.
    • Submit Service Request → eTIMS → OSCU (or VSCU). Enter your Integration Token and click Verify. Upload commitment form. Wait for approval SMS.
    • After approval, get branch office ID (and serial/equipment if required) from the portal or step-by-step guide.
  4. Implement initialization in your backend
    • POST to https://etims-api-sbx.kra.go.ke/selectInitOsdcInfo (or path in spec) with PIN, branch office ID, equipment info.
    • Parse and store the communication key (and any token/cert) for that connection. Use it for all subsequent calls.
  5. Implement in sequence
    • Basic data (get codes, branch list, etc.).
    • Branch information (send customer/branch and user accounts).
    • Item management → inventory item master.
    • Sales management → sales transaction + sales invoice; then credit note flow from spec.
    • Purchase transaction → get purchases, send confirmation.
    • Stock management → stock in/out, stock inventory.
  6. Map accounting tool ↔ eTIMS
    • Your sync-to-books (or similar) layer: transform accounting tool entities (invoices, items, stock, purchases) to eTIMS format and back; call the right OSCU endpoints in the right order; handle ETR receipts and errors.

​
7. Summary

If the portal requires an Integration Token for both OSCU and VSCU, obtain it by applying for certification with the eTIMS Bio Data Form (see Section 0). After certification, use your token on the Service Request form; then use the credentials (PIN, branch office ID, communication key) from device initialization for all API calls. Use the Technical Spec v2.0 for exact APIs and the Step-by-Step Guide for sign-up, approval, and sequence.