KRA PIN Registration API

Register new individual KRA PINs through the developer.go.ke API. This endpoint supports individual taxpayer registration using National ID, Passport, or other identification documents.

Table of Contents

1. Overview
2. Register Individual PIN
3. Field Reference
4. Taxpayer Types
5. Status Codes

Overview

Required Scope

Endpoint Summary

Note: This endpoint is for individual taxpayers only. Company/non-individual PIN registration requires a different process through the KRA portal.

Register Individual PIN

Submit an individual PIN registration request to KRA.

Endpoint: POST /api/kra/registration/pin

Required Scope: kra:registration

Request Body:

You can submit fields in either flat or nested format. Salami wraps flat fields inside TAXPAYERDETAILS automatically.

Flat Format

{
  "TaxpayerType": "1",
  "IdentificationNumber": "12345678",
  "DateOfBirth": "1990-05-15",
  "MobileNumber": "0712345678",
  "EmailAddress": "john.doe@example.com",
  "IsPinWithNoOblig": "Y"
}

Nested Format

{
  "TAXPAYERDETAILS": {
    "TaxpayerType": "1",
    "IdentificationNumber": "12345678",
    "DateOfBirth": "1990-05-15",
    "MobileNumber": "0712345678",
    "EmailAddress": "john.doe@example.com",
    "IsPinWithNoOblig": "Y"
  }
}

Parameter Table

Request:

curl -X POST \
  https://yourtenant.salami.dgl.co.ke/api/kra/registration/pin \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "TaxpayerType": "1",
    "IdentificationNumber": "12345678",
    "DateOfBirth": "1990-05-15",
    "MobileNumber": "0712345678",
    "EmailAddress": "john.doe@example.com",
    "IsPinWithNoOblig": "Y"
  }'

Success Response:

{
  "success": true,
  "data": {
    "KRAPIN": "A001234567B",
    "TaxpayerName": "JOHN DOE SMITH",
    "IdentificationType": "National ID",
    "IdentificationNumber": "12345678",
    "Status": "Registered",
    "RegistrationDate": "2026-03-29",
    "StationName": "NAIROBI",
    "Message": "PIN registered successfully. An SMS has been sent to the registered mobile number."
  },
  "message": "KRA PIN registered successfully"
}

Duplicate Response (already registered):

{
  "success": false,
  "message": "KRA API error: A PIN already exists for this identification number",
  "error": "kra_error",
  "kra_response": {
    "ExistingPIN": "A001234567B"
  }
}

Response Fields

Field Reference

TaxpayerType

IdentificationNumber

DateOfBirth

• Format: YYYY-MM-DD
• Must be a past date
• Applicant must be 18 years or older
• Example: 1990-05-15

MobileNumber

• Kenyan mobile number
• Format: 07XXXXXXXX or 01XXXXXXXX (10 digits)
• Can also use international format: 254712345678
• KRA sends a confirmation SMS to this number

EmailAddress

• Must be a valid email format
• KRA sends a confirmation email with PIN details
• Example: john.doe@example.com

IsPinWithNoOblig

Tip: Use Y for individuals who need a PIN only for identification purposes (e.g., opening a bank account, KRA agent registration). Use N when the individual will be filing tax returns.

Taxpayer Types

Individual (supported by this API)

Non-Individual (not supported)

Company, partnership, trust, and other non-individual registrations must be done through the KRA portal at itax.kra.go.ke.

Validation Errors

{
  "success": false,
  "message": "Required fields missing: TAXPAYERDETAILS.TaxpayerType, TAXPAYERDETAILS.IdentificationNumber, TAXPAYERDETAILS.DateOfBirth, TAXPAYERDETAILS.MobileNumber, TAXPAYERDETAILS.EmailAddress, TAXPAYERDETAILS.IsPinWithNoOblig",
  "error": "validation_error"
}

Status Codes

Best Practices

1. Verify first -- Use PIN by ID to check if a PIN already exists
2. Validate mobile number -- Ensure the mobile number is valid and reachable
3. Verify email -- Use a valid email; KRA sends the PIN certificate to this address
4. Store the PIN -- Save the returned KRA PIN in your system
5. Inform the user -- Let users know they will receive an SMS and email from KRA
6. Handle duplicates -- Gracefully handle the "PIN already exists" response
7. Sandbox testing -- Test with the sandbox environment first; sandbox may use test ID numbers

Related Documentation

• KRA Overview
• KRA Checkers - PIN by ID -- Check if a PIN already exists
• KRA Checkers - PIN Validation -- Validate a registered PIN

Back to: KRA Overview | KRA Returns