KRA PIN by PIN

Look up taxpayer details using a known KRA PIN (e.g. A123456789Z).

Request

POST/api/v1/kra-pin-by-pin

{{baseUrl}}/api/v1/kra-pin-by-pin

Header

Header	Type	Description
Authorization	string	`Bearer YOUR_ACCESS_TOKEN` from the OAuth client-credentials flow
Content-Type	string	application/json

Body Parameters

Parameter	Type	Description	Required
kra_pin	string	KRA PIN — A or P + 9 digits + letter (e.g. A123456789Z)	required
consent	boolean	Must be true — confirms data-subject consent to perform this verification	required
customer_number	string	Optional reference for your own tracking (max 255 characters)	optional

Sample request & response

Request payload for Sample request & response:

Sample dataRequest payload

{
  "kra_pin": "A123456789Z",
  "consent": true
}

Expected response for Sample request & response:

200 OKSample dataExpected response

{
  "success": true,
  "response_code": 200,
  "message": "KRA PIN by PIN verification successful",
  "data": {
    "taxpayer_id": "A123456789Z",
    "taxpayer_pin": "A123456789Z",
    "taxpayer_name": "JOHN DOE SAMPLE",
    "taxpayer_type": "Individual",
    "status": "Active"
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Response Fields

Field	Type	Description
success	boolean	Whether the request succeeded
response_code	number	Application response code (typically mirrors HTTP)
message	string	Human-readable status message
data	object	Payload for the verified resource
request_id	string	UUID for support and audit trails
data.taxpayer_pin	string	KRA PIN
data.taxpayer_name	string	Taxpayer name
data.taxpayer_type	string	Type of taxpayer from KRA
data.status	string	PIN status from KRA (StatusOfPIN). Possible values: Active, Suspended, Cancelled, Stopped

PIN status values

data.status maps from KRA StatusOfPIN. Possible values and meanings:

Status	Meaning
Active	The PIN is currently active in the tax system.
Suspended	The PIN has been temporarily suspended.
Cancelled	The PIN has been cancelled and is no longer active.
Stopped	The PIN has been stopped in the tax system.

Error codes

Standard Peleza HTTP / response_code values (same across all API calls). Validation message text is endpoint-specific. Full reference: Error Codes.

Code	When	Billed?
200	Taxpayer details returned	Yes
400	Validation — kra_pin required and must match A/P + 9 digits + letter	No
401	Missing or invalid Bearer token	No
402	Insufficient wallet balance or credit limit	No
403	No active wallet or billing profile (or service not enabled)	No
404	Invalid KRA PIN (code 19005)	Yes
408	Not typically used for KRA — upstream failures map to 503	No
429	Rate limited	No
502	Not typically used for KRA — upstream failures map to 503	No
503	KRA connection / service unavailable	No

Set {{baseUrl}} to https://api.peleza.com (production) or https://sandbox.peleza.com (sandbox). Authenticated calls need a Bearer token from POST /api/v1/oauth/token.