Quick Start

npm install xaqiiji-sdk

XAQIIJI_API_KEY=xq_test_xxxxxxxxxxxxxx# Optional — defaults to https://xaqiiji-api.ahmed-dalab.comXAQIIJI_BASE_URL=https://xaqiiji-api.ahmed-dalab.com

import { Xaqiiji } from "xaqiiji-sdk";const client = new Xaqiiji({  apiKey: process.env.XAQIIJI_API_KEY!,  environment: "test", // use "live" with xq_live_* keys});const result = await client.verify.citizen(  {    nationalId: "12345678901",    purpose: "pre_employment",  },  { idempotencyKey: "verify-2026-06-02-001" },);console.log(result.result);        // verified | not_found | expired | ...console.log(result.reference);     // certificate reference numberconsole.log(result.isCached);      // true when replayed within idempotency windowconsole.log(result.citizen?.fullName);

const history = await client.verify.list({ page: 1, limit: 10 });console.log(history.data.length);console.log(history.pagination.totalDocs);

import {  XaqiijiAuthError,  XaqiijiInsufficientCreditsError,  XaqiijiInvalidFormatError,  XaqiijiRateLimitError,} from "xaqiiji-sdk";try {  await client.verify.citizen({    nationalId: "12345678901",    purpose: "pre_employment",  });} catch (err) {  if (err instanceof XaqiijiInsufficientCreditsError) {    // Top up credits in the business portal  } else if (err instanceof XaqiijiInvalidFormatError) {    // National ID must be exactly 11 digits  } else if (err instanceof XaqiijiAuthError) {    // Missing, invalid, or revoked API key  } else if (err instanceof XaqiijiRateLimitError) {    // Back off using err.retryAfter (seconds)  } else {    throw err;  }}

result.result         // verified | not_found | expired | service_unavailableresult.reference      // certificate reference numberresult.isCached       // true when idempotent replayresult.creditDeducted // whether a credit was usedresult.citizen        // NIRA profile when available