API v1OpenAPI ready

API Overview

Live enterprise API endpoints for citizen verification. Use test keys (xq_test_*) in development and live keys (xq_live_*) in production.

API Reference introduction

The live Xaqiiji API today supports citizen verification and listing previous verifications. All requests use /api/v1 and Bearer API key authentication.

Base URLs

Sandbox

http://localhost:8080/api/v1

Use test API keys and mock verification data.

Production

https://xaqiiji-backend.onrender.com/api/v1

Use live API keys, real records, credits, and permanent audit logs.

Authentication summary

Requires API key authentication

Send requests from a trusted backend using Authorization: Bearer <api_key>. Never expose live API keys in frontend code.

Parameter	Type	Required	Description	Example
Authorization	string	required	Bearer API key from the business portal.	`Bearer xq_test_xxxxxxxxxxxxxx`
Content-Type	string	required	Request body format.	`application/json`
Idempotency-Key	string	recommended	Unique key (8–128 chars) for safe retries on POST /verify/citizen.	`verify-2026-06-02-001`

Response format

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

Error format

application/json

{  "status": "failed",  "code": "BAD_REQUEST",  "message": "Validation failed",  "errors": [    {      "field": "nationalId",      "message": "National ID must be exactly 11 digits"    }  ]}

HTTP status	Error code	Description
400	`BAD_REQUEST`	Malformed request or validation failure.
401	`UNAUTHORIZED`	Missing, invalid, revoked, or expired API key.
403	`FORBIDDEN`	Business inactive or not on an enterprise plan.
404	`NOT_FOUND`	Resource not found.
409	`CONFLICT`	Idempotency-Key reused with a different payload.
429	`RATE_LIMITED`	Too many requests — retry with backoff.
500	`INTERNAL_ERROR`	Unexpected server error.