Idempotency

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

How it works

Send an Idempotency-Key header on POST /api/v1/verify/citizen to safely retry failed requests without creating duplicate verifications.

Header format

Parameter	Type	Required	Description	Example
Idempotency-Key	string	recommended	Unique key, 8–128 characters.	`verify-2026-06-02-001`

Same key + same body

If you retry with the same key and identical JSON body within 24 hours, the API returns the original response with cached: true.

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

Conflict behavior

Reusing a key with a different request body returns 409 CONFLICT.

application/json

{  "status": "failed",  "code": "CONFLICT",  "message": "Idempotency-Key was already used with a different request payload"}

Best practices

Idempotency guidance

Generate one key per logical verification attempt

Reuse the same key when retrying network failures

Store keys with your internal reference ID

Do not reuse keys across different national IDs

Error Handling

Edit this page

Was this page helpful?