
20-10-2026
Qiwa API Integration Software Development in Saudi Arabia: Labour Compliance Endpoints, Work Permit Verification, and HRSD Platform Architecture (2026)

Quick Answer: Qiwa API integration connects an HR platform's employee and contract workflows with approved Qiwa services, where the necessary integration access is available. Before development, confirm the permitted APIs, access agreement, authentication requirements, and data-use conditions with HRSD or an authorised integration partner. Build employee-consent tracking, contract status management, work-permit reminders, Saudisation reporting, and audit records around the capabilities actually approved for your organisation.
Need Qiwa connected to your HR system? Book a 30-minute Qiwa integration review → · Prefer a ready-made platform? See Nasaq HRMS →
Qiwa is a central digital platform for employment contract management and labour-related services in Saudi Arabia. For HR software developers, integrating Qiwa into an existing workforce platform can reduce duplicate data entry, improve contract tracking, and give HR teams a clearer view of employee documentation and compliance tasks.
However, Qiwa API integration software development in Saudi Arabia involves more than connecting an application to an endpoint. Developers must establish which integration channels are available, confirm access permissions with the relevant authorities, account for employee approval workflows, and protect sensitive employee information.
This guide explains the integration architecture, the labour-compliance workflows to plan for, the access questions to resolve before development, and the costs involved in building a Qiwa-integrated HR platform.
The Qiwa API: Every Integration Endpoint Explained
A Qiwa-integrated HR platform should be designed around the business workflows it needs to support, rather than assuming that every operation available in the Qiwa portal has a corresponding public API.
The endpoint paths below are illustrative application-level API designs. They are not represented as verified public Qiwa endpoints. Actual API names, request formats, permissions, and response fields must come from the official documentation supplied for your approved integration.
1. Establishment Verification API
Illustrative internal endpoint: GET /api/establishments/{cr_number}
An establishment verification module can help HR teams maintain a consistent record of their organisation's registration details and relevant labour-compliance information.
Depending on the approved data source, the module may be designed to display:
- Commercial registration number and establishment identity.
- Establishment status, where available.
- Employee counts and Saudi employee counts, where authorised.
- Available Saudisation or Nitaqat information.
- The source and timestamp of the most recent verification.
Use case: An HR administrator needs to review establishment information before initiating an onboarding or compliance workflow.
Do not assume that an integration can retrieve every establishment field or a live Nitaqat classification. Confirm the permitted data fields and update frequency before defining the dashboard.
2. Employee Verification API
Illustrative internal endpoint: POST /api/employees/verify
Employee verification can be an important part of onboarding, particularly where HR teams need to review identity details, employment records, or work authorisation.
An internal verification workflow may accept a reference to the employee and the relevant establishment. It should retrieve only the information that the approved service is permitted to disclose.
Possible application-level outcomes include:
- Verification completed.
- Additional information required.
- Verification pending.
- Verification unsuccessful.
- Manual review required.
Use case: HR reviews an employee's documentation before completing the relevant onboarding tasks.
National ID numbers and Iqama details are sensitive personal information. Apply access controls, minimise stored identifiers, encrypt sensitive data, and avoid logging full identity numbers unnecessarily.
3. Employment Contract Management API
Illustrative internal endpoint: POST /api/contracts
Contract management is one of the most important workflows to consider when designing Qiwa API integration software.
HRSD's published Contract Management service explains that establishments can create and document employment contracts electronically. Employees can approve, reject, or request amendments through their Qiwa Afrad accounts. When both parties agree, the contract is certified and approved by HRSD.
A connected HR platform should therefore distinguish between creating a contract internally and completing the official documentation process.
Its internal contract record may contain:
- Employer and employee references.
- Job title and contract type.
- Salary and other agreed financial terms.
- Contract duration and working arrangements.
- Internal document version.
- Submission status and external reference, if returned.
- Employee response status, where available through an approved integration.
- Timestamps and the history of amendments.
Use case: HR prepares a contract in its own system and tracks the steps required to complete the corresponding Qiwa process.
Do not mark a contract as officially registered simply because it has been saved in the HR platform or submitted for approval. Maintain distinct states such as draft, submitted, pending_employee_action, approved, rejected, and amendment_requested, adjusting them to the actual statuses returned by the approved service.
4. Contract Amendment API
Illustrative internal endpoint: PUT /api/contracts/{contract_id}
Employment changes can involve salary adjustments, role changes, revised working arrangements, or other amendments.
The HR platform should preserve the original contract details and record each proposed change as a separate version. This provides a clear history of what changed, who initiated it, and whether the relevant approval process was completed.
A suitable workflow includes:
- An authorised HR user proposes an amendment.
- The application validates required fields.
- The amendment is submitted through the approved process, where available.
- The employee's response is tracked when the relevant status is accessible.
- HR is notified of approval, rejection, or a request for changes.
- The internal contract record is updated according to the confirmed outcome.
Do not hard-code an assumed HRSD review period or promise automatic approval. The processing time and required actions depend on the service and circumstances.
5. Work Permit Tracking API
Illustrative internal endpoint: GET /api/employees/{employee_id}/work-permit
A work-permit lifecycle module helps HR teams monitor relevant documentation and act before expiry dates create operational problems.
Depending on approved access, the module may support:
- Recording permit type and reference.
- Tracking known validity dates.
- Sending renewal reminders.
- Assigning follow-up tasks.
- Recording the status of renewal actions.
- Flagging missing or outdated information.
Use case: HR needs a central view of employee documentation and upcoming renewal tasks rather than checking dates across disconnected records.
An internal reminder system does not replace official verification. Clearly distinguish a date entered by an HR user from a date retrieved from an authorised government service.
6. Saudisation and Nitaqat Monitoring API
Illustrative internal endpoint: GET /api/establishments/{cr_number}/saudisation
Saudisation planning requires businesses to understand the applicable workforce requirements and how staffing changes may affect their compliance position.
A platform can provide a dashboard for available Saudisation data, track internal workforce composition, and flag hiring decisions that may require further review.
Potential features include:
- Saudi and non-Saudi workforce counts.
- The latest available compliance information.
- The date and source of each update.
- Configurable warnings for missing or stale data.
- Scenario planning based on proposed hires.
- Reports for authorised HR users.
The actual Saudisation requirements may depend on factors such as activity, establishment classification, workforce size, and applicable rules. Do not implement one universal minimum percentage for every employer.
Likewise, a projected Nitaqat outcome calculated by your software should be labelled as an estimate unless the authorised source explicitly provides that projection.
For high-impact hiring decisions, display the age of the underlying data and require a fresh verification when appropriate. A four-hour refresh policy can be considered as an internal control for selected high-risk workflows, but it should not be described as an official HRSD requirement without confirmation.
7. Labour Complaint Management API
Illustrative internal endpoint: POST /api/labour-cases
Some HR platforms need to maintain records of employee concerns, disputes, and related administrative actions.
A case-management module can record the issue, assigned HR contact, supporting documents, communication history, and internal follow-up dates.
However, internal case management is different from filing a formal complaint with HRSD. Do not assume that an external complaint-submission API exists or that a private HR platform is authorised to file complaints on an employee's behalf.
If formal case submission is a requirement, confirm the approved service, authorised user roles, consent requirements, and supported response data before building that capability.
8. Employee Transfer Workflow API
Illustrative internal endpoint: POST /api/employees/{employee_id}/transfer-requests
Businesses that manage employee transfers need to track the relevant documentation, actions, and status changes.
An internal workflow can record a transfer request, the employee and establishment references, the responsible administrator, outstanding actions, and the latest verified status.
Whether the application can initiate a formal transfer or retrieve its official status depends on the services and permissions available to the organisation.
Do not hard-code universal transfer timelines or assume that employer consent and dispute handling follow one fixed process. Verify the applicable conditions for each supported workflow.
Mapping Qiwa into your own HR platform?
Logiolegion builds the contract, work-permit and Saudisation workflows above into existing HR systems. If you would rather not build, Nasaq HRMS is Logiolegion's ready-made Saudi HR platform. Send us your current setup and we will tell you which route is faster.
Book a 30-minute Qiwa integration review →
The Three Prerequisites Most Developers Miss
1. Confirm the HRSD Integration and Access Requirements
A common planning mistake is assuming that Qiwa works like a standard public API, where a developer creates an account, generates an API key, and starts making requests.
Do not assume that model applies.
Before committing to production integration, establish:
- Whether the required API or approved integration channel exists.
- Whether direct access is available to your organisation.
- Whether a formal service agreement or separate approval is required.
- Which endpoints and data fields are permitted.
- What authentication, network, and security controls apply.
- Whether a sandbox, test account, or sample payloads are available.
- Whether a third-party integration partner is authorised to provide the required service.
The access process and its duration must be confirmed directly. A six-to-ten-week approval period, for example, should be treated as a planning assumption until the relevant authority or partner confirms it.
Architecture implication: Keep external-service access as an explicit project dependency. The engineering team can design internal data models, user interfaces, and state transitions while access is being resolved, but it should not promise a working production integration before the necessary permissions and technical specifications are available.
2. Design for Employee Consent and Contract Status
Qiwa's contract-management workflow demonstrates why an employer's internal record and an official contract outcome must remain distinct. Employees can approve, reject, or request amendments through their Qiwa Afrad accounts. https://www.hrsd.gov.sa/en/ministry-services/services/%D8%A5%D8%AF%D8%A7%D8%B1%D8%A9-%D8%A7%D9%84%D8%B9%D9%82%D9%88%D8%AF
Build an explicit state machine rather than a single contract_registered Boolean.
A simplified example:
Draft
|
v
Ready for Submission
|
v
Submitted
|
v
Awaiting Employee Action
|
+----> Approved
|
+----> Rejected
|
+----> Amendment Requested
The actual states and transitions should reflect the approved integration's documented responses and the official process.
The HR platform should notify the relevant HR users when action is required, retain submission references, and avoid reporting a pending contract as complete.
Employee-facing instructions should be available in clear Arabic and English where appropriate. This is especially useful when employees are unfamiliar with the approval process or the language used in the contract.
3. Keep Saudisation Data Fresh and Traceable
A dashboard can create a false sense of certainty if its underlying compliance information is old.
Track the source, timestamp, and freshness of data used in hiring decisions. Where a current external value cannot be retrieved, make that limitation visible rather than silently presenting an old result as current.
For establishments near a compliance threshold, the application can require a fresh check or additional HR review before a decision is finalised.
Avoid claiming that HRSD recalculates every establishment's Nitaqat status at a specific interval unless that timing has been verified. The system should follow the update cadence documented for the approved data source.
The Cost of Manual Qiwa Workflows — and When Integration Breaks Even
Manual portal work creates recurring administrative overhead, especially when HR maintains employee details in one system and re-enters them into another.
Typical tasks include contract preparation, status checks, permit-expiry monitoring, workforce reporting, and follow-up with employees whose actions remain pending.
Consider an illustrative employer with 80 employees whose HR team spends 12–15 hours per month on these activities. If the organisation values that time at SAR 8,000 per month, that becomes the baseline for comparing process improvements.
However, the financial benefit depends on how much work the integration actually removes. Some activities still require human review, employee action, or work through the official portal.
Calculate the potential return using:
- Current monthly administrative cost.
- The proportion of tasks that can genuinely be automated.
- Implementation and ongoing support costs.
- Provider or access-related costs, if applicable.
- Training and process-change costs.
- The value of improved tracking and fewer missed follow-ups.
An 18–24-month break-even period should be treated as a scenario to validate with the employer's actual figures, not a guaranteed outcome.
The Eight Core Modules of a Qiwa-Integrated HR Platform
1. Establishment Dashboard
Displays establishment information, available Saudisation data, outstanding tasks, and alerts. Each externally sourced value should show when it was last verified.
2. Employee Onboarding and Verification
Maintains employee records, tracks required documents, and supports authorised verification workflows. Where identity verification through NAFATH is required, assess it as a separate approved integration rather than assuming Qiwa automatically exposes NAFATH functionality.
Read more about NAFATH API integration in Saudi Arabia.
3. Contract Management Engine
Supports contract preparation, version control, submission tracking, employee-action states, amendments, and notifications.
4. Work Permit Lifecycle Manager
Tracks available permit details, expiry dates, renewal tasks, and follow-up responsibilities. Official status should only be displayed as verified when supported by an authorised source.
5. Saudisation Hiring Decision Support
Combines internal workforce data with the latest available authorised compliance information. Any projected hiring impact should be clearly identified as an estimate unless provided by an official source.
6. Payroll Compliance Bridge
Connects employment and salary records with the payroll workflow so that discrepancies can be flagged for review.
Qiwa and Mudad serve different functions. Qiwa supports employment-related services, including contract management, while Mudad is associated with wage protection and payroll-related compliance services. Their integration should be designed around the capabilities and permissions of each service.
A payroll platform may also need to consider the Wage Protection System and the applicable salary-disbursement process. See Saudi HR payroll app development: Mudad, GOSI, and WPS.
7. Labour Case Management
Maintains internal case records, supporting documents, responsible users, and follow-up tasks. Formal external complaint submission should only be added when an approved service supports it.
8. Qiwa Audit Trail
Records user actions, internal contract versions, submission attempts, external references, and status changes.
The audit trail should make it possible to answer questions such as who initiated a contract, when it was submitted, what response was received, and why the internal status changed.
Apply appropriate access controls and retention policies to the audit records, particularly when they contain employee identifiers or employment information.
The Five-Step Qiwa Integration Build Process
Step 1 — Resolve Access and Requirements
Confirm the available integration channel, service agreement requirements, permitted data, and approval process. In parallel, document the HR workflows and prepare the system architecture.
Step 2 — Build the Contract and Verification Workflows
Implement the internal employee and contract data models, contract versioning, status tracking, and notifications.
Use an approved sandbox or test environment if one is available. Until the external specifications are confirmed, build against clearly labelled mock responses rather than invented production endpoints.
Step 3 — Implement Saudisation and Permit Tracking
Build the establishment dashboard, data-freshness controls, permit reminders, and hiring-review workflows. Connect external data only through the approved source.
Step 4 — Connect Payroll and Related Services
Map the relevant contract and salary fields to internal payroll records. Add reconciliation checks and define how discrepancies will be handled.
Where Mudad, GOSI, WPS, or another government-related service is required, confirm its own access and integration requirements separately. One integration does not automatically grant access to another.
Step 5 — Test, Approve, and Launch
Test the complete workflow using the authorised environment and data. Include pending employee actions, rejected contracts, amendments, expired documents, failed requests, duplicate events, and unavailable external services.
Complete user acceptance testing with HR stakeholders and validate the audit trail before enabling the production workflow.
The project timeline should be finalised after confirming external access, API availability, and the required scope. Do not commit to a production launch date based solely on an assumed approval window.
What Does Qiwa API Integration Cost in Saudi Arabia?
The following figures are indicative software-development planning ranges, not official Qiwa fees or verified market averages. Actual costs depend on the confirmed integration route, project scope, access conditions, and external-service requirements.
| Project scope | Indicative development budget | Indicative timeline |
|---|---|---|
| Qiwa-related module for an existing HR platform | SAR 90,000–160,000 | 10–14 weeks |
| Full HR platform with contract and workforce modules | SAR 200,000–360,000 | 16–22 weeks |
| Enterprise platform with multiple establishments and connected payroll workflows | SAR 380,000–600,000 | 20–30 weeks |
These ranges assume that the required technical access and integration route can be established. External approval delays, unavailable APIs, additional security requirements, or the need for manual operational work may change both the cost and timeline.
A useful project estimate should separate discovery, platform development, integration work, testing, deployment, and ongoing support. It should also identify any external provider fees separately rather than presenting them as confirmed Qiwa charges.
Why Logiolegion for Saudi HR Platform Development?
Logiolegion develops custom software and business platforms for organisations that need their applications to reflect real operational and compliance workflows.
For a Saudi HR platform, the work can include employee and contract management, payroll workflow integration, Arabic-first interfaces, audit logging, and approved government-service connections.
Our approach starts by identifying which integrations are actually available, which workflows can be automated, and which steps still require employee or HR action. That reduces the risk of building a platform around undocumented endpoints or unconfirmed access assumptions.
We can also assess the wider Saudi compliance stack. Qiwa, NAFATH, and ZATCA serve different purposes, and they are not universally mandatory as a group for every HR platform. The integrations required depend on the product's functions, the employer's obligations, and the applicable service requirements.
For invoice and tax workflows, see ZATCA Fatoorah API integration in Saudi Arabia. For broader product engineering, explore our custom software development company in Saudi Arabia guide.
Final Thoughts
Qiwa API integration software development in Saudi Arabia begins with a clear understanding of the approved integration route, not a list of assumed endpoints.
A well-designed HR platform can centralise contract records, track employee actions, monitor documentation, support workforce reporting, and connect relevant payroll workflows. The implementation must also distinguish internal records from official outcomes, protect employee information, and maintain a traceable audit history.
The most important first step is to confirm the integration access and documentation available for your use case. Once those dependencies are understood, the engineering team can define the architecture, delivery phases, budget, and production-readiness criteria.
Building a Qiwa-integrated HR platform for Saudi Arabia? Book a free discovery call with Logiolegion to scope the HRSD access requirements, contract-consent workflow, workforce modules, and integration architecture.
Frequently Asked Questions
1. What is Qiwa API integration software development in Saudi Arabia?
It is the process of connecting an HR or workforce platform with approved Qiwa services to support relevant employment-related workflows. The available capabilities depend on the integration route, permissions, and technical documentation provided for the specific use case.
2. Does Qiwa provide a public API that any developer can use?
Do not assume that all Qiwa portal functions are available through a public API. Confirm the available integration channel, access conditions, permitted endpoints, and approval requirements with HRSD or an authorised integration partner before development.
3. Is a formal HRSD service agreement required for Qiwa API access?
The applicable agreement and approval requirements must be confirmed for the intended integration. Establish this early in the project and obtain written confirmation of the access route and its conditions.
4. Can an HR platform register employment contracts directly with Qiwa?
That depends on whether the required contract-management integration is available and authorised for the organisation. The application should also track employee approval or rejection and should not mark a contract as officially completed merely because it exists in the internal HR system.
5. Can Qiwa API integration verify work permits and Iqama validity?
Only if the approved integration or another authorised source exposes the required information. An HR platform can track recorded expiry dates and send reminders without claiming that those records constitute live government verification.
6. How does Qiwa integration support Nitaqat and Saudisation monitoring?
A platform can combine internal workforce information with authorised Saudisation data to support reporting and hiring reviews. Requirements vary by the applicable classification and rules, so estimates should not be presented as official Nitaqat determinations.
7. How does Qiwa connect with Mudad, GOSI, and WPS?
These services address different parts of the Saudi employment and payroll environment. A platform may connect their relevant workflows, but each integration's availability, permissions, and technical requirements must be assessed separately.
8. How much does Qiwa API integration cost in Saudi Arabia?
Development costs depend on the existing HR platform, required modules, access arrangements, and the complexity of contract, workforce, and payroll workflows. The ranges in this guide are planning estimates, not official Qiwa fees or guaranteed project quotations.
9. How long does Qiwa integration take?
The timeline depends on the scope, availability of technical documentation, external approvals, testing requirements, and production access. Confirm the integration dependencies before committing to a launch date.
10. Can Logiolegion build a complete HR platform with Qiwa integration?
Logiolegion can scope the HR platform, contract-management workflows, workforce reporting, payroll connections, and integration architecture. Any direct Qiwa integration remains subject to the access and technical capabilities confirmed for the project.
Continue Reading
Discover our full range of services - from custom software development to complete marketing solutions

Best HRMS Software in Saudi Arabia (2026)
Compare the best HRMS and HR software in Saudi Arabia for 2026: Nasaq, Jisr, Bayzat, ZenHR, SAP and Oracle for GOSI, Qiwa, Mudad, Nitaqat and cloud HR.

Custom HRMS or Nasaq? A Decision Guide for Saudi HR Leads
Custom HRMS or Nasaq? Compare Saudi payroll compliance ownership, update responsibility, costs, timelines, and the case for building versus subscribing.

How to Build a Saudi HR and Payroll App: Mudad, GOSI, and WPS Compliance for 2026
Building HR software for Saudi Arabia in 2026 requires more than payroll processing. This guide explains how to build a fully compliant HR and payroll platform integrated with Qiwa, Mudad, GOSI, Nitaqat, and Muqeem — including WPS automation, dual GOSI calculations, AI compliance monitoring, Arabic RTL interfaces, and the real architecture required to avoid costly compliance mismatches.

Saudi HR Software That Handles Mudad, GOSI, Qiwa, and Nitaqat — A 2026 Guide for Saudi HR Managers
Discover what a fully Saudi-compliant HRMS should include in 2026. Learn how custom Saudi HR software automates Mudad WPS, GOSI payroll, Qiwa contracts, Nitaqat tracking, PDPL compliance, and Saudi payroll workflows while reducing compliance risk and manual HR administration.

