blog hero background

20-10-2026

Qiwa API Integration Software Development in Saudi Arabia: Labour Compliance Endpoints, Work Permit Verification, and HRSD Platform Architecture (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:

  1. An authorised HR user proposes an amendment.
  2. The application validates required fields.
  3. The amendment is submitted through the approved process, where available.
  4. The employee's response is tracked when the relevant status is accessible.
  5. HR is notified of approval, rejection, or a request for changes.
  6. 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 scopeIndicative development budgetIndicative timeline
Qiwa-related module for an existing HR platformSAR 90,000–160,00010–14 weeks
Full HR platform with contract and workforce modulesSAR 200,000–360,00016–22 weeks
Enterprise platform with multiple establishments and connected payroll workflowsSAR 380,000–600,00020–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.


Have An Idea That Needs To Go Mobile? Launch It With Us!

Have an idea that needs to go mobile? Launch it with us!

Share

Continue Reading

Discover our full range of services - from custom software development to complete marketing solutions

footer-background-image

Your Vision, Our Logic — Let's Build The Future Together.

At Logiolegion, we don't just build software — we engineer logical, future-ready solutions for your goals. Let's create something remarkable, together.

Let's Talk Business
LogioLegion logo

Logiolegion ©2026 All rights reserved

contact@logiolegion.com

+91 8590143573

Forging Logical Solutions