National ID

Verify a Ugandan National ID or voter record. The default is a NIN lookup. For a voter lookup, send id_type=voter with first_name and last_name.

Test data

Sandbox test data

Use these values against the sandbox host. Click a value to copy it.

Sample NIN (fictional)

Sample voter number (fictional)

Request

POST/api/v1/id/ug

{{baseUrl}}/api/v1/id/ug

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	Ugandan NIN (default) or voter number when id_type=voter	required
id_type	string	"nin" (default) or "voter"	optional
first_name	string	Required when id_type=voter	conditional
last_name	string	Required when id_type=voter	conditional
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

NIN (default)

Sample request body for NIN (default):

Sample dataSample request body

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

Sample response for NIN (default):

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"
}

id_type=voter

Sample request body for id_type=voter:

Sample dataSample request body

{
  "id_number": "87654321",
  "id_type": "voter",
  "first_name": "John",
  "last_name": "Musa",
  "consent": true
}

Sample response for id_type=voter:

200 OKSample dataSample response

{
  "success": true,
  "response_code": 200,
  "message": "Uganda ID details fetched successfully",
  "country": "ug",
  "data": {
    "id_number": "87654321",
    "first_name": "John",
    "last_name": "Musa",
    "other_name": null,
    "name": "John Musa",
    "dob": "1992-04-10",
    "gender": "Male",
    "valid": true,
    "voter_number": "87654321",
    "district": "Sample District",
    "constituency": "Sample Constituency",
    "polling_station": "Sample Polling Station"
  },
  "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	Country code — always "ug" for this route
data.id_number	string	NIN or voter number
data.first_name	string	Given name
data.last_name	string	Surname
data.other_name	string	Other / middle name
data.name	string	Full display name
data.dob	string	Date of birth (YYYY-MM-DD)
data.gender	string	Gender
data.valid	boolean	Whether the ID is valid
data.voter_number	string	Present on voter lookups
data.district	string	Present on voter lookups
data.constituency	string	Present on voter lookups
data.polling_station	string	Present on voter lookups

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	Uganda ID details returned successfully	Yes
400	Validation — missing/invalid id_number, consent (must be true), or Uganda-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	Uganda 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 first name field is required when id type is voter",
  "country": "ug",
  "errors": {
    "first_name": "The first name field is required when id type is voter"
  },
  "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.