National ID

Verify a Kenyan national ID via POST /api/v1/id/ke. Required body: id_number, consent (must be true), and scope — "basic" for demographics or "full" for the richer record plus photo / fingerprint / signature URLs when available. Billing: basic → national-id; full → national-id-image. HTTP 200 and 404 (ID not found) are billable; validation 400 is not. Error codes below are the same for all Peleza API calls — see Error Codes for the full reference.

Loading sandbox test IDs…

Request

POST/api/v1/id/ke

{{baseUrl}}/api/v1/id/ke

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
id_number	string	Kenyan national ID number (numeric, 6–10 digits)	required
consent	boolean	Must be true — confirms data-subject consent to perform this verification	required
scope	string	Must be "basic" (demographics) or "full" (full record + media URLs when available)	required
customer_number	string	Optional reference for your own tracking (max 255 characters)	optional

scope=basic

Sample request body for scope=basic:

Sample dataSample request body

{
  "id_number": "12345678",
  "consent": true,
  "scope": "basic"
}

Sample response for scope=basic:

200 OKSample dataSample response

{
  "success": true,
  "response_code": 200,
  "message": "Kenya ID details fetched successfully",
  "country": "ke",
  "data": {
    "id_number": "12345678",
    "serial_number": "237314661",
    "first_name": "JOHN",
    "last_name": "DOE",
    "other_name": "SAMPLE",
    "name": "DOE JOHN SAMPLE",
    "gender": "Male",
    "dob": "1990-01-01",
    "citizenship": "Kenyan",
    "valid": true
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

scope=full

Sample request body for scope=full:

Sample dataSample request body

{
  "id_number": "12345678",
  "consent": true,
  "scope": "full"
}

Sample response for scope=full:

200 OKSample dataSample response

{
  "success": true,
  "response_code": 200,
  "message": "Kenya ID with full details fetched successfully",
  "country": "ke",
  "data": {
    "full_name": "DOE JOHN SAMPLE",
    "first_name": "JOHN",
    "last_name": "DOE",
    "other_name": "SAMPLE",
    "id_number": "12345678",
    "serial_number": "237314661",
    "date_of_birth": "1990-01-01",
    "gender": "Male",
    "citizenship": "Kenyan",
    "verification_status": "Valid",
    "clan": "SAMPLE CLAN",
    "ethnic_group": "SAMPLE ETHNIC GROUP",
    "family": "SAMPLE FAMILY",
    "occupation": "Engineer",
    "pin": "A123456789Z",
    "place_of_birth": "Nairobi, Kenya",
    "place_of_death": null,
    "place_of_live": "Nairobi, Kenya",
    "reg_office": "Nairobi",
    "date_of_death": null,
    "date_of_issue": "2010-06-18",
    "photo_url": "https://cdn.example.com/id_card_images/photo_xxx.jpeg",
    "fingerprint_url": null,
    "signature_url": "https://cdn.example.com/id_card_images/signature_xxx.jpeg",
    "has_photo": true,
    "has_fingerprint": false,
    "has_signature": true,
    "is_valid": true
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440001"
}

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
country	string	Country code — always "ke" for this route
data.id_number	string	National ID number
data.serial_number	string	ID serial number when available
data.first_name	string	Given name(s)
data.last_name	string	Surname
data.other_name	string	Other / middle name
data.name	string	Full display name (basic scope)
data.gender	string	Gender
data.dob	string	Date of birth (YYYY-MM-DD) on basic scope
data.citizenship	string	Citizenship
data.valid	boolean	Whether the ID is valid
data.full_name	string	Full name (full scope)
data.date_of_birth	string	Date of birth (full scope)
data.photo_url	string	CDN photo URL (full scope, when available)
data.fingerprint_url	string	CDN fingerprint URL (full scope, when available)
data.signature_url	string	CDN signature URL (full scope, when available)
request_id	string	UUID for support and audit trails

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	ID details returned successfully	Yes
400	Validation — missing/invalid id_number, scope (must be basic\|full), or consent (must be true)	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	ID not found — or unsupported country	Yes for ID-not-found; No for unsupported country
408	Upstream timeout / service error	No
429	Rate limited	No
502	Upstream bad or unreadable response	No
503	Upstream connection unavailable	No

400 — validation

400Sample data400 — validation

{
  "success": false,
  "response_code": 400,
  "message": "The scope field is required",
  "country": "ke",
  "errors": {
    "scope": "The scope field is required"
  },
  "data": null,
  "request_id": "550e8400-e29b-41d4-a716-446655440010"
}

404 — ID not found

404Sample data404 — ID not found

{
  "success": false,
  "response_code": 404,
  "message": "Kenya ID not found",
  "description": "There is no information for requested search parameters",
  "country": "ke",
  "data": null,
  "request_id": "550e8400-e29b-41d4-a716-446655440013"
}

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.