First API Request

Step-by-step guidance for secure Xaqiiji API integration.

Endpoint summary

POST/api/v1/verify/citizen

Verify Citizen

Verify a citizen using an 11-digit national ID.

Required headers

Parameter	Type	Required	Description	Example
Authorization	string	required	Bearer API key (xq_test_* or xq_live_*)	`Bearer xq_test_xxx`
Content-Type	string	required	Request body format	`application/json`
Idempotency-Key	string	recommended	Unique key to prevent duplicate side effects on retry	`verify-2026-06-02-001`

Request body

application/json

{  "nationalId": "12345678901",  "purpose": "pre_employment"}

Response body

application/json

{  "message": "Verification completed",  "cached": false,  "creditDeducted": true,  "data": {    "id": "uuid",    "result": "verified",    "purpose": "pre_employment",    "channel": "api",    "creditsUsed": 1  },  "citizen": {    "fullName": "Example Citizen",    "dateOfBirth": "1990-01-01"  }}

Field explanations

Parameter	Type	Required	Description	Example
nationalId	string	required	11-digit national ID	`12345678901`
purpose	string	required	Verification purpose (e.g. pre_employment)	`pre_employment`
cached	boolean	response	True if returned from recent cache	`false`
creditDeducted	boolean	response	Whether a credit was used	`true`

Common mistakes

Avoid these issues

Missing Authorization header

Using portal JWT instead of API key for server calls

National ID not exactly 11 digits

Retrying POST without Idempotency-Key

Logging national IDs in plain text

Next steps

Handle errors, configure webhooks, then test sandbox response scenarios before production.

Quick Start

Authentication

Edit this page

Was this page helpful?