Country ID Verification

Verify a national identity document by country. Supported codes: ke, ao, ug, za, zm, zw, gh, ng. Kenya requires consent and scope (basic or full). Other countries require consent and return country-specific fields. All docs examples use fictional sample data only — see each country page for identifier formats.

Loading sandbox test IDs…

Request

POST/api/v1/id/{country}

{{baseUrl}}/api/v1/id/{country}

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	National / voter / NIN / NRC identifier for the country	required
consent	boolean	Must be true — confirms data-subject consent to perform this verification	required
scope	string	Required for Kenya (ke) — "basic" or "full"	conditional
id_type	string	UG: nin\|voter (default nin). GH: card\|voter (default card). NG: nin\|nin_advance (optional)	optional
first_name	string	Required for Uganda when id_type=voter	conditional
last_name	string	Required for Uganda when id_type=voter	conditional
full_name	string	Optional for Ghana voter flows	optional
is_new_id	boolean	Optional for Ghana	optional
customer_number	string	Optional reference for your own tracking (max 255 characters)	optional

Kenya (scope=basic)

Sample request body for Kenya (scope=basic):

Sample dataSample request body

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

Sample response for Kenya (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"
}

Nigeria NIN

Sample request body for Nigeria NIN:

Sample dataSample request body

{
  "id_number": "12345678901",
  "consent": true
}

Sample response for Nigeria NIN:

200 OKSample dataSample response

{
  "success": true,
  "response_code": 200,
  "message": "Nigeria ID details fetched successfully",
  "country": "ng",
  "data": {
    "nin": "12345678901",
    "id_number": "12345678901",
    "first_name": "Ada",
    "last_name": "Okafor",
    "middle_name": null,
    "name": "Ada Okafor",
    "dob": "1995-03-12",
    "gender": "Female",
    "phone_number": "+2348012345678",
    "photo_url": null,
    "valid": true
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Uganda NIN

Sample request body for Uganda NIN:

Sample dataSample request body

{
  "id_number": "CM123456789AB",
  "consent": true
}

Sample response for Uganda NIN:

200 OKSample dataSample response

{
  "success": true,
  "response_code": 200,
  "message": "Uganda ID details fetched successfully",
  "country": "ug",
  "data": {
    "id_number": "CM123456789AB",
    "first_name": "John",
    "last_name": "Musa",
    "other_name": null,
    "name": "John Musa",
    "dob": "1992-04-10",
    "gender": "Male",
    "valid": true
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Ghana Card

Sample request body for Ghana Card:

Sample dataSample request body

{
  "id_number": "GHA-123456789-0",
  "consent": true
}

Sample response for Ghana Card:

200 OKSample dataSample response

{
  "success": true,
  "response_code": 200,
  "message": "Ghana ID details fetched successfully",
  "country": "gh",
  "data": {
    "id_number": "GHA-123456789-0",
    "voter_number": "GHA-123456789-0",
    "first_name": "Kwame",
    "last_name": "Mensah",
    "name": "Kwame Mensah",
    "gender": "Male",
    "full_name": "Kwame Mensah",
    "is_new_id": null,
    "valid": true
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

South Africa ID

Sample request body for South Africa ID:

Sample dataSample request body

{
  "id_number": "9001015800085",
  "consent": true
}

Sample response for South Africa ID:

200 OKSample dataSample response

{
  "success": true,
  "response_code": 200,
  "message": "South Africa ID details fetched successfully",
  "country": "za",
  "data": {
    "id_number": "9001015800085",
    "first_name": "Thabo",
    "last_name": "Ndlovu",
    "middle_name": null,
    "name": "Thabo Ndlovu",
    "gender": "Male",
    "dob": "1990-01-01",
    "marital_status": "Single",
    "living_status": "Alive",
    "phone_number": "+27821234567",
    "address": "123 Sample Street, Johannesburg",
    "issued_date": "2010-06-15",
    "photo_url": null,
    "valid": true
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Angola ID

Sample request body for Angola ID:

Sample dataSample request body

{
  "id_number": "000000000LA000",
  "consent": true
}

Sample response for Angola ID:

200 OKSample dataSample response

{
  "success": true,
  "response_code": 200,
  "message": "Angola ID details fetched successfully",
  "country": "ao",
  "data": {
    "id_number": "000000000LA000",
    "first_name": "Maria",
    "last_name": "Silva",
    "name": "Maria Silva",
    "active_status": "ATIVO",
    "valid": true
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Zambia NRC

Sample request body for Zambia NRC:

Sample dataSample request body

{
  "id_number": "123456/78/1",
  "consent": true
}

Sample response for Zambia NRC:

200 OKSample dataSample response

{
  "success": true,
  "response_code": 200,
  "message": "Zambia ID details fetched successfully",
  "country": "zm",
  "data": {
    "nrc": "123456/78/1",
    "id_number": "123456/78/1",
    "tpin": "100284531",
    "taxpayer_name": "Chanda Banda",
    "current_status": "Active",
    "is_deregistered": false,
    "tax_types": ["PAYE", "VAT"],
    "valid": true
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Zimbabwe ID

Sample request body for Zimbabwe ID:

Sample dataSample request body

{
  "id_number": "63-123456A12",
  "consent": true
}

Sample response for Zimbabwe ID:

200 OKSample dataSample response

{
  "success": true,
  "response_code": 200,
  "message": "Zimbabwe ID details fetched successfully",
  "country": "zw",
  "data": {
    "id_number": "63-123456A12",
    "first_name": "Tendai",
    "last_name": "Moyo",
    "name": "Tendai Moyo",
    "dob": "1988-06-20",
    "gender": "Female",
    "citizenship": "Zimbabwean",
    "valid": true
  },
  "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
country	string	ISO2 country code from the path (ke, ao, ug, za, zm, zw, gh, ng)
data	object	Country-specific identity fields — see each country page

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	Country ID details returned successfully	Yes
400	Validation — missing/invalid id_number, consent (must be true), or Country-specific fields	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	Country 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 consent field is required",
  "country": "ug",
  "errors": {
    "consent": "The consent 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": "Uganda ID not found",
  "description": "There is no information for requested search parameters",
  "country": "ug",
  "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.