Verify Citizen
Verify Somali citizens using National ID. These endpoints are live today.
Purpose
Verify Somali citizens using National ID. These endpoints are live today.
Endpoint group cards
/api/v1/verify/citizenVerify citizen
Verify a Somali citizen identity using 11-digit National ID.
/api/v1/verificationsList verifications
List previous verification requests for your business.
/api/v1/docs/openapi.jsonOpenAPI specification
Machine-readable contract for SDK generation and validation.
Detailed endpoint
/api/v1/verify/citizenVerify citizen
Verify a Somali citizen identity using National ID.
Real-time
Under 2 seconds
Requires API Key
Bearer token
Rate Limit
60 req/min
Credits
1 credit per request
Overview
Verify a Somali citizen identity using National ID. This endpoint is designed for secure server-to-server integrations and returns structured JSON suitable for enterprise audit, reporting, and ERP reconciliation.
Requires API key authentication
Send requests from a trusted backend using Authorization: Bearer <api_key>. Never expose live API keys in frontend code.
Rate limit: 60 requests per minute
Use idempotency keys and exponential backoff. Retry only after the reset window or the Retry-After header.
Request
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| nationalId | string | required | 11-digit Somali National ID. | 12345678901 |
| purpose | string | optional | Business purpose for audit logs. | pre_employment |
| Idempotency-Key | header | recommended | Unique key (8–128 chars) for safe retries. | verify-2026-06-02-001 |
| Authorization | header | required | Bearer API key (xq_test_* or xq_live_*). | Bearer xq_test_xxxxxxxxxxxxxx |
{ "nationalId": "12345678901", "purpose": "pre_employment"}Response
{ "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" }}Code Examples
curl -X POST "http://localhost:8080/api/v1/verify/citizen" \ -H "Authorization: Bearer xq_test_xxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: verify-2026-06-02-001" \ -d '{ "nationalId": "12345678901", "purpose": "pre_employment"}'Errors
{ "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. |
Rate Limits
Rate limit: 60 requests per minute
Use idempotency keys and exponential backoff. Retry only after the reset window or the Retry-After header.