Integrating Qiwa with Your HR System: Saudi 2026 Guide

As of April 15, 2026, the rules changed. The Saudi Ministry of Human Resources and Social Development (MHRSD) made a single decision that put every private-sector HR team in the Kingdom on high alert: only Saudi nationals with electronically authenticated contracts on Qiwa count toward your Saudization rate.

That means your Nitaqat band — and everything that depends on it — now lives inside a platform that your HR system may not yet know how to talk to.

This guide covers the three integration levels available, the data flow between Qiwa and the wider government stack (Mudad, GOSI, Muqeem), and the common pitfalls that cause contracts to fail authentication.

Why Qiwa Integration Became Non-Negotiable in 2026

Qiwa, operated by Takamol Holding under MHRSD, is Saudi Arabia's centralized digital labor market portal. It has handled employment contracts, work permits, and Saudization monitoring for years — but April 2026 made it the single source of truth for Nitaqat calculations.

The compliance timeline:

• April 15, 2026 — GOSI-only registration no longer counts toward Saudization
• April 30, 2026 — Companies must reach 85% of Saudi national contracts documented electronically on Qiwa
• June 30, 2026 — Threshold rises to 90%

Missing these targets cascades into penalties: Nitaqat color-band demotion, expatriate quota freezes, work visa suspension, government tender ineligibility, and administrative fines from MHRSD.

Manual portal entry works for small establishments. For any company with 50-plus employees, the volume makes automation the only sustainable path.

The Saudi Government Platform Stack

Qiwa does not operate in isolation. Understanding the full stack prevents data conflicts that silently break your compliance:

The critical rule: the salary figure in your Qiwa contract must exactly match what flows into Mudad. A one-riyal discrepancy triggers a compliance flag and the Saudi employee loses Saudization credit until resolved.

Three Integration Levels

Level 1 — Portal Only (Manual)

HR staff log into qiwa.sa, create contracts through the web interface, and monitor status manually. Zero integration cost, but processing time scales linearly with headcount. Viable only under 20 employees.

Level 2 — ERP Plugin

Certified HR software vendors (SAP SuccessFactors, Oracle HCM, Zoho People, PalmHR, DocSuite) offer pre-built Qiwa connectors. The connector handles authentication, contract formatting, and status syncing inside the existing HR interface. This is the fastest path to automation for teams already on a major HRMS.

Level 3 — Direct REST API

For custom-built systems, on-premise ERPs, or workflows not served by existing connectors, direct integration via Qiwa's REST APIs gives full control. This is the approach this guide focuses on.

REST API Integration: The Technical Walkthrough

Prerequisites

Before your first API call you need:

1. Commercial Registration (CR) active and linked to Qiwa
2. Digital certificate from Takamol Holding — this authenticates your system to the Qiwa API (separate from Nafath/Absher)
3. Authorized delegate registered in Qiwa Business account
4. Test environment access — Qiwa provides a sandbox for integration testing

Authentication Flow

Qiwa uses an OAuth 2.0 client credentials flow. Your system obtains a bearer token using the digital certificate, then includes it in every API call:

const getQiwaToken = async () => {
  const response = await fetch('https://api.qiwa.sa/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: process.env.QIWA_CLIENT_ID,
      client_secret: process.env.QIWA_CLIENT_SECRET,
    }),
  });
  const data = await response.json();
  return data.access_token;
};

Contract Generation and Submission

The core workflow for a new hire:

const submitContract = async (token: string, contractData: ContractPayload) => {
  const response = await fetch('https://api.qiwa.sa/v1/contracts', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
      'X-Establishment-ID': process.env.QIWA_ESTABLISHMENT_ID,
    },
    body: JSON.stringify({
      employee_national_id: contractData.nationalId,
      monthly_salary: contractData.salary,
      job_title: contractData.jobTitle,
      contract_start_date: contractData.startDate,
      contract_duration_months: contractData.durationMonths,
      work_location: contractData.workLocation,
    }),
  });
  return response.json();
};

After submission, the contract enters a pending employee acceptance state. The Saudi national employee must log into their Qiwa Individuals account and accept the contract digitally before it counts toward Saudization. Your system should poll the contract status endpoint or subscribe to webhook events to track this step.

Nitaqat Status Polling

const getNitaqatStatus = async (token: string) => {
  const response = await fetch('https://api.qiwa.sa/v1/establishment/nitaqat', {
    headers: { 'Authorization': `Bearer ${token}` },
  });
  const data = await response.json();
  return {
    band: data.nitaqat_band,         // Platinum | High Green | Mid Green | Low Green | Red
    saudizationRate: data.saudi_percentage,
    pendingContracts: data.pending_authentication_count,
  };
};

Polling this weekly — or triggering on contract status changes — gives your HR dashboard a live Nitaqat view without manual portal logins.

Common Integration Failures and How to Fix Them

1. Salary mismatch with Mudad The most common cause of Saudization credit loss. Your contract submission to Qiwa must use the gross monthly salary that Mudad will process. Allowances, deductions, and bonuses need to match the payroll configuration exactly.

2. Employee acceptance timeout Qiwa requires the employee to accept their contract — the employer cannot force this step. Contracts pending acceptance for more than 30 days are typically voided. Automate reminder messages to employees (WhatsApp or SMS) at 7 days and 14 days after submission.

3. Multi-establishment groups Companies with multiple CRs must manage separate Qiwa Business accounts per establishment. Your integration must route each contract to the correct establishment ID, or Nitaqat calculations fragment across unrelated entities.

4. Work permit prerequisite failures Foreign national contracts submitted before the Iqama or work permit is active in Muqeem will be rejected. Add a Muqeem status check before submitting non-Saudi contracts.

Connecting the Stack: Mudad and GOSI Sync

Once a contract is accepted in Qiwa, your integration should trigger downstream actions:

1. Push salary data to Mudad to activate Wage Protection System coverage
2. Register the employee in GOSI for social insurance contributions
3. For expatriates, verify Muqeem residency status is current

A clean integration handles all three in a single new-hire workflow rather than as three separate manual tasks. The WPS compliance guide covers the Mudad side of this stack in detail.

For companies also managing ZATCA e-invoicing alongside HR compliance, the Saudi e-invoicing integration guide covers the parallel API stack.

What Automated Qiwa Management Saves

Manual Qiwa management for a company with 200 employees typically consumes 15–20 hours per month of HR staff time: entering contracts, checking statuses, chasing employee acceptances, and exporting Nitaqat reports. A REST API integration cuts that to under two hours — monitoring exceptions rather than processing every case.

At a broader level, the cost of workflow automation in the Saudi market follows the same pattern across every government platform: the integration cost pays back in the first quarter.

Ready to Integrate Your HR System with Qiwa?

If your HR team is still manually entering contracts on qiwa.sa, the June 2026 threshold of 90% authentication is the last warning before penalties become systematic. Your Nitaqat band protects your ability to hire expatriates, bid on government tenders, and renew employee residency permits.

Our team has built Qiwa integrations across SAP, Oracle, and custom ERP environments in the Saudi market. If you want a diagnostic of your current compliance gap and an integration roadmap, start the conversation here.