Manual Submissions

Submit an individual national ID for manual verification. Step 1: call List Countries below for supported ISO codes. Step 2: POST with country, type, and id (biodata and files optional). Step 3: fetch results with GET /api/v1/kyc/manual/{batch_token}. Use the sandbox sample IDs below when testing against the sandbox host.

Test data

Sandbox test data

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

Sandbox eligible countries

Sandbox — Complete (RW)

Sandbox — Complete (TZ)

Sandbox — Processing (stays in_progress)

Sandbox — Unable to verify

More complete IDs (sandbox)

List countries

Returns the countries where Peleza supports manual national ID verification. Call this endpoint before submitting to obtain valid ISO country codes (for example RW, TZ). Optional query: ?q= filters by country name or ISO code (case-insensitive). Auth required; this call is not billed.

GET/api/v1/kyc/countries

{{baseUrl}}/api/v1/kyc/countries

List all eligible countries

200 OKSample dataExpected response

{
  "success": true,
  "response_code": 200,
  "message": "Countries retrieved successfully",
  "data": {
    "countries": [
      { "code": "RW", "name": "Rwanda" },
      { "code": "TZ", "name": "Tanzania" }
    ]
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Filter by name or code (q=rw)

200 OKSample dataExpected response

{
  "success": true,
  "response_code": 200,
  "message": "Countries retrieved successfully",
  "data": {
    "countries": [
      { "code": "RW", "name": "Rwanda" }
    ]
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Field	Type	Description
data.countries	array	Eligible countries for manual national ID verification, sorted alphabetically by name
data.countries[].code	string	ISO 3166-1 alpha-2 country code — use this value as country on POST /api/v1/kyc/manual
data.countries[].name	string	Human-readable country name

Submit verification

POST/api/v1/kyc/manual

{{baseUrl}}/api/v1/kyc/manual

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
country	string	ISO country code — e.g. RW, TZ	required
type	string	national_id (only supported type today)	required
id	string	National ID / document number	required
first_name	string	Given name. Omit the field, or send null / empty string.	optional
middle_name	string	Middle name. Omit the field, or send null / empty string.	optional
last_name	string	Family name. Omit the field, or send null / empty string.	optional
date_of_birth	string	Date of birth as YYYY-MM-DD. Must be in the past if provided.	optional
gender	string	Male, Female, M, or F (any case)	optional
files	array	Supporting documents as base64 in the JSON body. Max 10 files, 10 MB decoded each.	optional
files[].filename	string	Original file name — e.g. id-front.jpg	optional
files[].mime_type	string	MIME type — e.g. image/jpeg	optional
files[].content	string	Raw base64 or a data URI	optional

Sandbox sample — Complete (RW)

Request payload for Sandbox sample — Complete (RW):

Sample dataRequest payload

{
  "country": "RW",
  "type": "national_id",
  "id": "85940685"
}

Expected response for Sandbox sample — Complete (RW):

200 OKSample dataExpected response

{
  "success": true,
  "response_code": 202,
  "message": "Manual verification submitted successfully",
  "data": {
    "batch_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "national_id",
    "status": "in_progress",
    "submitted_at": "2026-08-27T10:56:00.000000Z",
    "note": "This verification requires manual processing and is typically completed within 24-48 hours.",
    "waiting_time": 2
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Sandbox sample — Complete (TZ)

Request payload for Sandbox sample — Complete (TZ):

Sample dataRequest payload

{
  "country": "TZ",
  "type": "national_id",
  "id": "8594068345"
}

Expected response for Sandbox sample — Complete (TZ):

200 OKSample dataExpected response

{
  "success": true,
  "response_code": 202,
  "message": "Manual verification submitted successfully",
  "data": {
    "batch_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "national_id",
    "status": "in_progress",
    "submitted_at": "2026-08-27T10:56:00.000000Z",
    "note": "This verification requires manual processing and is typically completed within 24-48 hours.",
    "waiting_time": 2
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Sandbox sample — Processing (RW)

Request payload for Sandbox sample — Processing (RW):

Sample dataRequest payload

{
  "country": "RW",
  "type": "national_id",
  "id": "MANUAL0001"
}

Expected response for Sandbox sample — Processing (RW):

200 OKSample dataExpected response

{
  "success": true,
  "response_code": 202,
  "message": "Manual verification submitted successfully",
  "data": {
    "batch_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "national_id",
    "status": "in_progress",
    "submitted_at": "2026-08-27T10:56:00.000000Z",
    "note": "This verification requires manual processing and is typically completed within 24-48 hours.",
    "waiting_time": 2
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

With optional biodata and files (TZ sandbox)

Request payload for With optional biodata and files (TZ sandbox):

Sample dataRequest payload

{
  "country": "TZ",
  "type": "national_id",
  "id": "8594068345",
  "first_name": "Jane",
  "last_name": "Doe",
  "date_of_birth": "1991-06-12",
  "gender": "Female",
  "files": [
    {
      "filename": "id-front.jpg",
      "mime_type": "image/jpeg",
      "content": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAYEBQYFBAYGBQYHBwYIChAKCgkJChQODwwQFxQYGBcU"
    }
  ]
}

Expected response for With optional biodata and files (TZ sandbox):

200 OKSample dataExpected response

{
  "success": true,
  "response_code": 202,
  "message": "Manual verification submitted successfully",
  "data": {
    "batch_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "national_id",
    "status": "in_progress",
    "submitted_at": "2026-08-27T10:56:00.000000Z",
    "note": "This verification requires manual processing and is typically completed within 24-48 hours.",
    "waiting_time": 2
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Duplicate in-progress request (HTTP 200)

Request payload for Duplicate in-progress request (HTTP 200):

Sample dataRequest payload

{
  "country": "RW",
  "type": "national_id",
  "id": "85940685"
}

Expected response for Duplicate in-progress request (HTTP 200):

200 OKSample dataExpected response

{
  "success": true,
  "response_code": 200,
  "message": "Manual verification already in progress",
  "data": {
    "batch_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "national_id",
    "status": "in_progress",
    "submitted_at": "2026-08-27T10:56:00.000000Z",
    "waiting_time": 2
  },
  "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.batch_token	string	UUID — fetch results with GET /api/v1/kyc/manual/{batch_token}
data.type	string	national_id
data.status	string	in_progress on accept; complete or unable_to_verify after processing
data.submitted_at	string	ISO 8601 timestamp
data.note	string	Processing SLA note (returned on HTTP 202 only)
data.waiting_time	integer	Present when status is in_progress — estimated turnaround in days (currently 2, i.e. 24–48 hours). Returned on HTTP 202 submit and on status polls while in_progress.

Fetch results

Fetch results using the batch_token from the submit response. On sandbox, use the sample IDs above — complete IDs return verification_result; MANUAL0001/MANUAL0002 stay in_progress; UNKNOWN999/UNKNOWN888 return unable_to_verify.

GET/api/v1/kyc/manual/{token}

{{baseUrl}}/api/v1/kyc/manual/{token}

Sandbox — Complete (RW · ${MANUAL_RW_COMPLETE_ID})

200 OKSample dataExpected response

{
  "success": true,
  "response_code": 200,
  "message": "Status retrieved successfully",
  "data": {
    "batch_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "national_id",
    "status": "complete",
    "submitted_at": "2026-08-27T10:56:00.000000Z",
    "verification_result": {
      "first_name": "John",
      "last_name": "Doe",
      "other_name": null,
      "gender": "Male",
      "dob": "1990-01-08",
      "citizenship": "Rwandan",
      "id_number": "85940685",
      "valid": true,
      "name": "Doe John"
    }
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Sandbox — Complete (TZ · ${MANUAL_TZ_COMPLETE_ID})

200 OKSample dataExpected response

{
  "success": true,
  "response_code": 200,
  "message": "Status retrieved successfully",
  "data": {
    "batch_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "national_id",
    "status": "complete",
    "submitted_at": "2026-08-27T10:56:00.000000Z",
    "verification_result": {
      "first_name": "Jane",
      "last_name": "Doe",
      "other_name": null,
      "gender": "Female",
      "dob": "1991-06-12",
      "citizenship": "Tanzanian",
      "id_number": "8594068345",
      "valid": true,
      "name": "Doe Jane"
    }
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Sandbox — Processing (RW · ${MANUAL_RW_PROCESSING_ID})

200 OKSample dataExpected response

{
  "success": true,
  "response_code": 200,
  "message": "Status retrieved successfully",
  "data": {
    "batch_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "national_id",
    "status": "in_progress",
    "submitted_at": "2026-08-27T10:56:00.000000Z",
    "waiting_time": 2
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Sandbox — Unable (RW · ${MANUAL_RW_UNABLE_ID})

200 OKSample dataExpected response

{
  "success": true,
  "response_code": 200,
  "message": "Status retrieved successfully",
  "data": {
    "batch_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "national_id",
    "status": "unable_to_verify",
    "submitted_at": "2026-08-27T10:56:00.000000Z"
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Field	Type	Description
data.batch_token	string	UUID from the submit response
data.type	string	national_id
data.status	string	in_progress \| complete \| unable_to_verify
data.submitted_at	string	ISO 8601 timestamp
data.waiting_time	integer	Present when status is in_progress — estimated turnaround in days (currently 2)
data.verification_result	object	Omitted while in_progress or unable_to_verify; present when status is complete
data.verification_result.first_name	string	Verified given name
data.verification_result.last_name	string	Verified family name
data.verification_result.other_name	string\|null	Verified other / middle name
data.verification_result.gender	string	Verified gender
data.verification_result.dob	string	Verified date of birth (YYYY-MM-DD)
data.verification_result.citizenship	string	Citizenship label, e.g. Rwandan
data.verification_result.id_number	string	Verified national ID number
data.verification_result.valid	boolean	true when the ID was successfully verified
data.verification_result.name	string	Display name — last_name first_name other_name

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.