Odoo Muqeem Integration: Iqama, Visas, GOSI and KSA Payroll Guide

Saudi HR teams juggle Muqeem for residency, GOSI for social insurance, Qiwa for contracts and Mudad for wages, often with a spreadsheet in the middle. Our Odoo integration services connect these portals to one Odoo employee record.

This guide is for HR managers, payroll officers and finance leads at Saudi companies with expatriate staff who run Odoo 19 or plan Odoo 20. For the wider country rollout, read our guide to Odoo ERP implementation in Saudi Arabia.

What does an Odoo Muqeem integration actually do?

An Odoo Muqeem integration lets HR issue and renew iqamas and visas from the employee form instead of logging in to the Muqeem portal for each case. The employee data already in Odoo fills the request, and the result comes back to the same record.

Muqeem is the portal Saudi establishments use for expatriate residency services. A typical connector covers these actions:

• Exit re-entry visas: issue single or multiple visas, extend them, or cancel them.
• Final exit visas: issue and cancel final exit for leaving staff.
• Iqama renewal: renew residency for a set number of months.
• Sponsorship transfer: move an employee to a new sponsor ID.
• Reports: print Arabic employee reports and reprint visas by number.
• Audit trail: log each request, response and returned PDF in the chatter.

That list comes from a Muqeem integration module on the Odoo Apps Store, which renews iqamas for 3 to 24 months and lists versions 15.0 to 19.0. Other partners sell similar modules, so compare scope line by line.

What do Odoo 19 and Odoo 20 cover natively for Saudi HR?

Odoo 19 already ships a Saudi payroll localization, and Odoo 20 adds GOSI integration, sick leave and end of service rules, and a nationalization report. Muqeem is missing from both.

Saudi HR task	Odoo 19	Odoo 20
Saudi salary structure (KSA Employee)	Yes	Yes
Iqama ID, iqama cost and medical insurance on employee	Yes	Yes
WPS file for Mudad	Yes	Yes
GOSI integration (contribution percentages)	Not in the docs	Yes, via GOSI API credentials
Sick leave and end of service rules	Not in the docs	Yes
Nitaqat nationalization % report	Not in the docs	Yes
Muqeem iqama and visa actions	Third-party module	Third-party module

The comparison is based on the Odoo 20 Saudi Arabia payroll documentation and the Odoo 19 version of the same page. Test any feature in your own database before you count on it.

If you are choosing a version for a new Saudi rollout, our Odoo 19 vs Odoo 20 comparison covers the wider trade-offs. Our Odoo 20 payroll release notes list the general payroll changes.

How does the Odoo GOSI integration work in Odoo 20?

The Odoo GOSI integration connects Payroll to the GOSI portal so the contribution percentages for each insurance branch come from GOSI, not from a hand-typed table. Payslips then use those rates for both employee and employer.

GOSI runs three branches: Annuities, Occupational Hazards and Unemployment Insurance (SANED). Odoo retrieves the percentages for all three and applies them through two salary rules, one for the employee share and one for the employer share.

Set it up in Payroll, Configuration, Settings, under GOSI Integration. You need six values from the GOSI portal: Registration Number, API Key, Client ID, Client Secret, DPoP Key and API Mode.

Odoo warns that the DPoP key must match GOSI's format exactly, as one missing space causes an error. After saving, click Test Connection, then check that every employee has a correct Iqama number on the Payroll tab.

The employee's nationality on the Personal tab decides which GOSI rate applies. The payslip PDF shows only the employee contribution; the employer share stays in your internal cost figures.

What GOSI contribution rates must Odoo KSA payroll reflect?

Odoo KSA payroll has to apply different GOSI rates to legacy Saudi staff, Saudi staff registered after 3 July 2024 and non-Saudi staff. The GOSI integration fetches them, but your payroll team should still know the numbers.

Group	Employee share	Employer share
Saudi, registered before 3 July 2024	9% annuities + 0.75% SANED	9% annuities + 0.75% SANED + 2% hazards
Saudi, registered on or after 3 July 2024	Rising in 0.5-point yearly steps	Rising in 0.5-point yearly steps
Non-Saudi	None	2% occupational hazards
Contribution wage cap	SAR 45,000 a month	SAR 45,000 a month

These figures follow Zoho's Saudi GOSI payroll documentation, which says the newer annuity rate reached 9.5% in July 2025 and keeps rising to 11% in July 2028. Always confirm the current rate in your GOSI portal.

An illustrative example: a legacy Saudi employee with SAR 10,000 of basic salary plus housing pays SAR 975 (9.75%), and the employer pays SAR 1,175 (11.75%). For a non-Saudi employee on the same wage, the employer pays SAR 200 and the employee pays nothing.

How do you set up Odoo Saudi payroll step by step?

Odoo Saudi payroll setup follows a fixed order: company IDs, employee data, payroll settings, then a test pay run. Skipping a step usually shows up later as a rejected WPS file.

1. Install the modules: Saudi Arabia Payroll (`l10n_sa_hr_payroll`) and Saudi Arabia Payroll with Accounting (`l10n_sa_hr_payroll_account`).
2. Complete the company: 15-digit VAT number, MoL number in Company ID, full address and SAR currency.
3. Set payroll settings: a trusted Establishment Bank Account with its Bank Establishment ID and SARIE code, the MoL Establishment ID, and the leave type for annual balance.
4. Fill each employee: nationality, a trusted IBAN, the 10-digit Saudi National or Iqama ID, and Pay Category set to KSA Employee.
5. Enter allowances and costs: monthly housing, transport and other allowances, plus the yearly iqama, medical insurance and work permit cost.
6. Connect GOSI (Odoo 20): add the portal credentials and test the connection.
7. Run a test pay run: validate work entries, compute payslips, post journal entries and generate a WPS file.

Odoo blocks payroll for any employee without a trusted bank account, and the dashboard shows a warning first. Clean bank data before go-live, not on payday.

Yearly iqama, medical insurance and work permit costs are spread monthly as employer costs. They sit in accounts such as 400014 Visa Expenses and 106012 Prepaid Employee Expenses, and never reduce the employee's net pay.

How do iqama renewal and exit re-entry visas work from Odoo?

Odoo iqama renewal and exit re-entry visas work through a Muqeem connector that sends the request with your establishment's Muqeem credentials and stores the result on the employee. The Muqeem side must be switched on first.

Muqeem API access is not automatic. HR software vendor Bayzat explains that you need the comprehensive (Shamel) Muqeem package, then subscribe to the integration under the Indirect API Package and pay through Sadad.

Bayzat also states that Muqeem charges 12% to 20% of the pro-rata subscription cost to enable API use. Government fees, such as the iqama renewal fee, are still paid through Sadad as on the portal.

On the Odoo side, the usual setup stores the main Muqeem username and password per company. Muqeem forces password changes, so whoever owns that login must update Odoo too, or requests start failing.

The iqama number on the employee record does double duty. GOSI and WPS need it for payroll, and Muqeem needs it for residency actions, so one clean field serves all three.

How does the Odoo WPS file reach Mudad?

Odoo builds the Saudi WPS file from validated payslips, and HR uploads it to Mudad Business to prove wages were paid. Odoo does not upload the file to Mudad for you.

The Odoo docs say the WPS report follows the technical guidelines issued by the Ministry of Human Resources and Social Development. You can create it per payslip or per pay run, with a payment date, WPS value date and optional debit date.

The ministry's wage protection upload service runs on Mudad Business. It is free, processed immediately, and updates the establishment's compliance rate once the file is accepted.

Most rejected files trace back to master data: a missing iqama ID, a bank account not marked trusted, or a wrong establishment ID. Check those three fields before every first run in a new company.

Muqeem API integration options: buy, build or partner?

Most Saudi companies should start from an existing Muqeem module and adapt it, as a full custom build only pays off with unusual workflows. The table compares the three routes.

Route	Best for	Watch out for
Buy an Odoo Apps Store module	Standard visa and iqama actions	Version support, licence, Odoo Online limits
Partner-supplied connector	Teams that want setup and support in one contract	Lock-in to that partner's code
Custom build on the Muqeem API	Approval chains, bulk renewals, custom reports	Higher build cost and upkeep each version

The Apps Store module we reviewed lists a price of US$2,862.42, an LGPL-3 licence and dependencies on Employees and Discuss only. Budget for setup, testing and upgrades on top, as our guide to third-party Odoo module costs explains.

Odoo Online does not accept custom or Apps Store modules, so a Muqeem connector means Odoo.sh or on-premise. On the Odoo pricing page that hosting comes with the Custom plan at US$61.00 per user a month billed yearly in the US.

If your connector also talks to Odoo from outside, plan for Odoo 20's API changes. XML-RPC and JSON-RPC are deprecated in Odoo 20 and scheduled for removal in Odoo 22; our JSON-2 API migration guide covers the move.

What risks should you control in a Saudi HR integration?

The main risks are expired credentials, bad master data and rules that change without anyone noticing. A short control list prevents most payday surprises.

• Credential owner: name one person for the Muqeem and GOSI logins and their renewals.
• Access rights: limit who can issue final exit visas or transfer sponsorship from Odoo.
• Rule parameters: Odoo advises editing Saudi rule parameters only when a national rule has changed.
• Iqama expiry alerts: add a scheduled activity well before each iqama expiry date, set by your own HR policy.
• Testing: run a parallel month of payroll against your old system before you switch.
• Version upgrades: retest the Muqeem module on a copy before each Odoo upgrade.

Saudi Arabia also requires Arabic on tax invoices, as the Odoo 20 Saudi fiscal localization guide notes. Plan Arabic labels for HR letters and reports at the same time.

Saudi HR compliance by industry

Industries with large expatriate workforces get the most from linking Muqeem, GOSI and payroll in Odoo. The pain points differ by sector.

Industry	Pain or cost driver	Odoo approach	How iVentureTeam helps
Construction	Many expatriate workers, frequent visas	Muqeem actions from the employee form	Bulk renewal views and approvals
Retail and restaurants	Shift staff, Nitaqat quotas per branch	Nationalization report by department	Set department minimum wages
Manufacturing	Overtime and late attendance deductions	Attendance-based work entries	Configure schedules and grace periods
Logistics	Drivers on exit re-entry visas	Visa tracking with chatter history	Expiry alerts tied to dispatch
Professional services	High salaries near the GOSI cap	GOSI rates fetched by API	Test cap handling in a pay run

How iVentureTeam helps with Odoo Muqeem integration

We connect Muqeem, GOSI and Mudad workflows to Odoo payroll and test them on your own employee data before go-live. We have delivered 150+ ERP projects across 35+ countries with 40+ Odoo specialists over 13+ years.

• Saudi payroll setup: KSA salary structure, allowances, end of service and leave rules.
• Muqeem connector: install, adapt or build the module through our Odoo customization services.
• GOSI connection: credential setup, rate checks and a parallel payroll month.
• WPS readiness: bank, iqama and establishment data cleaned before the first Mudad upload.
• Budget clarity: our published Odoo implementation cost ranges show mid-size projects at $9k to $27k over 8 to 14 weeks; try the Odoo project estimate tool for a first number.

The bottom line on Odoo Muqeem integration

Use Odoo 20's native Saudi payroll and GOSI integration, and add a tested Muqeem module for iqama and visa work. That gives HR one employee record for payroll, social insurance and residency.

Start with clean master data: iqama IDs, trusted IBANs and establishment IDs. Then connect GOSI, run a parallel payroll month, and switch on Muqeem actions once the credentials and approvals are in place.

Ready to connect Muqeem and GOSI to your Odoo payroll?

Get a scoped plan for your Saudi HR integration from a team that works with Odoo payroll. Plan your Odoo Muqeem and GOSI setup with us, call +91-90235-15208, or email business@iventureteam.com.