OCTA Gov Integrations Gateway — API v1
Base URL: https://gov.medcoreapp.tech (deployment setting PUBLIC_DOMAIN). All bodies are JSON (UTF-8). All responses are {"success": true, "data": …} or {"success": false, "error": "…"}. Error messages are in Arabic and safe to show to end users.
Overview
The gateway connects HR/ERP systems (MedCore, OCTAPOS, any ERP) to Saudi labour and immigration platforms — Qiwa, Muqeem and Mudad — and tracks every recurring compliance obligation: iqama expiries, exit/re-entry and final-exit visas, Qiwa contract documentation, and the monthly wage-protection (WPS) upload.
Honesty rule. None of these agencies publishes a public API. The gateway never invents an endpoint or field name. Each agency runs in one of three modes per establishment:
| Mode | What it does | Status |
|---|---|---|
file | Published file format where one exists (Mudad: WPS wages file per the HRSD specification), otherwise a status log with reminders; the action itself is done on the agency portal and recorded here | Live |
api | Direct integration through the agency/partner channel contracted in the establishment's name | Refuses to run (409 channel_not_ready) until the agency documentation is received and an adapter is written to it |
sandbox | Deterministic simulation for development and demos | Every reference starts with SANDBOX- and every result carries "simulated": true |
Sources used (see GET /v1/agencies):
- Qiwa contract documentation is required for Saudis to count in Nitaqat, effective 15 April 2026 — https://www.hrsd.gov.sa/en/node/5580136
- WPS Wages File Technical Specification (HRSD) — https://www.hrsd.gov.sa/sites/default/files/2017-06/WPS%20Wages%20File%20Technical%20Specification.pdf
- Mudad WPS upload service — https://www.hrsd.gov.sa/ministry-services/services/wage-protection-file-upload-service
- Mudad upload window reduced to 30 days from 1 March 2025 — https://www.hrsd.gov.sa/n/5573339
Authentication
| Header | Use |
|---|---|
X-API-Key: ogg_… | Server-to-server (MedCore, OCTAPOS, subscribed systems) |
Authorization: Bearer <token> | Dashboard sessions (/portal/login) |
Internal OCTA apps get a key from POST /admin/apps (or manage.py create-app) and have no subscription limits. Every resource is scoped to the calling app: an id belonging to another app returns 404, never 403.
Rate limit: RATE_LIMIT_PER_MINUTE per app (default 600) → 429.
Conventions
- Money is a string with exactly two decimals:
"6000.00". Floats are rejected (400). No silent rounding. - Dates are Gregorian
YYYY-MM-DD. "Today" is Asia/Riyadh. - Actors:
created_by,approver_ref,executed_by,actorare user ids in the calling system. The gateway enforces maker-checker on them, so pass the real user, never a shared constant. With a dashboard session the identity is the signed-in member and the body field is ignored. - Idempotency:
external_refis unique per establishment for tenants, employees and operations. Repeating a create with the sameexternal_refreturns the existing record (200). - Sensitive data: national ID / iqama numbers and IBANs are encrypted at rest and never returned — only
id_last4/iban_last4.
| Status | Meaning |
|---|---|
| 400 | Invalid input |
| 401 | Bad or revoked key / expired session |
| 402 | Subscription inactive or quota reached (sandbox is always free) |
| 403 | Not allowed (e.g. the creator trying to approve) |
| 404 | Not found or belongs to another app |
| 409 | State conflict, hash mismatch, or code: "channel_not_ready" |
| 429 | Rate limited |
| 502 | Agency channel error |
Establishments
POST /v1/tenants — create or update.
{"external_ref": "hospital-12", "name": "…", "cr_number": "1010…", "approvals_required": 1}
approvals_required is 1–3 approvers (none of whom may be the creator).
- GET /v1/tenants · GET /v1/tenants/{tid}
- PUT /v1/tenants/{tid}/settings
{"alert_days": {"iqama_expiry": [90,60,30,14,7,0], "exit_reentry": [7,3,0], "final_exit": [7,0],
"qiwa_contract": [60,30,7], "wps_month": [10,5,1,0]},
"wps": {"salary_due_day": 27}}
salary_due_day null = last day of the month (a configurable default, not a regulation).
POST /v1/tenants/{tid}/approvers — {"ref": "user:57", "name": "HR Manager", "max_amount": "500000.00" | null, "member_id": null, "active": true}. max_amount applies to WPS runs. GET lists them.
Channels
POST /v1/tenants/{tid}/channels — one channel per agency per establishment (re-posting changes mode/config; changing mode drops stored secrets).
{"agency": "qiwa" | "muqeem" | "mudad", "mode": "file" | "api" | "sandbox", "config": {…}}
Mudad in file mode needs the establishment's own data — there are no defaults:
| config key | WPS field | Rule |
|---|---|---|
sarie_bank_id | [DEST-ID] | 4 uppercase letters — from the establishment's bank (SARIE table) |
estb_id | [ESTB-ID] | up to 10 digits |
mol_estb_id | [MOL-ESTBID] | 2–15 digits |
establishment_iban | [BANK-ACC] | Saudi IBAN (24) |
layout.bank_only_fields | — | empty (all 14 columns, bank columns blank) or establishment_only — confirm with the bank (the spec is ambiguous) |
layout.line_ending | — | CRLF or LF — confirm with the bank |
layout.language | — | ar or en (one language per file) |
- GET /v1/tenants/{tid}/channels · GET /v1/channels/{cid} — each includes
readiness: {ready, problems[]}. - PUT /v1/channels/{cid}/secrets —
{"secrets": {…}}(credentials issued to the establishment by the agency). Encrypted; only key names are ever echoed. - POST /v1/channels/{cid}/sync — pull new statuses (
sandbox, andapionce available).
Employees
POST /v1/tenants/{tid}/employees — one object, or {"employees": [ … up to 2000 ]}. The whole request is validated before anything is written.
{"external_ref": "emp-301", "name_ar": "…", "name_en": "…", "id_number": "2xxxxxxxxx",
"iban": "SA…", "iqama_expiry": "2027-03-01", "nationality": "EGY", "occupation": "…",
"hire_date": "2024-01-01", "status": "active" | "terminated"}
id_number: 10 digits, starting with 1 (national ID → Saudi) or 2 (iqama). Unique per establishment. Creating an employee derives obligations: qiwa_contract for everyone and iqama_expiry for iqama holders with an expiry date.
- GET /v1/tenants/{tid}/employees?status= · GET /v1/employees/{eid} (includes the employee's obligations)
Obligations
Kinds and statuses are the gateway's own tracking model — not agency field values.
| kind | agency | statuses | due_date |
|---|---|---|---|
qiwa_contract | qiwa | not_started, submitted, awaiting_employee, documented, rejected, ended | contract end |
iqama_expiry | muqeem | valid, renewal_requested, renewed, expired | iqama expiry |
exit_reentry | muqeem | issued, departed, extended, returned, cancelled, expired_not_returned | return-by |
final_exit | muqeem | issued, departed, cancelled | leave-by |
wps_month | mudad | pending, file_ready, sent_to_bank, bank_processed, uploaded, compliant, non_compliant | upload deadline = salary due date + 30 days |
- GET /v1/tenants/{tid}/obligations?kind=&status=&due_before=&employee_id=
- GET /v1/obligations/{oid} — with
history[](status log) andallowed_next[]. - POST /v1/obligations/{oid}/status — the status log for
filemode:
{"status": "documented", "actor": "user:12", "note": "…", "evidence_ref": "…",
"new_expiry": "2027-11-01", // iqama_expiry → renewed
"new_due_date": "2026-12-20"} // exit_reentry → extended
- POST /v1/tenants/{tid}/obligations — record a visa issued on Muqeem (file mode):
{"kind": "exit_reentry" | "final_exit", "visa_ref": "…", "employee_id": "…", "due_date": "…", "actor": "…"}. - POST /v1/tenants/{tid}/wps/months —
{"period": "2026-11"}opens a WPS month (the sweeper also opens last month automatically when a Mudad channel exists). - GET /v1/tenants/{tid}/compliance — summary: Saudis without a documented contract, iqamas expired/expiring, open/overdue visas, last 12 WPS months, open alerts.
Date-driven changes run in the sweeper: an iqama past its date becomes expired; an exit/re-entry still departed/extended after its return-by date becomes expired_not_returned.
Alerts
Raised once per (obligation, due date, threshold). Levels: info (>30 days), warning (≤30), critical (≤3 or overdue). A Saudi employee whose contract is not documented raises nitaqat_not_counted:*.
- GET /v1/tenants/{tid}/alerts?all=1
- POST /v1/tenants/{tid}/alerts/evaluate — run now (the sweeper runs it hourly).
- POST /v1/tenants/{tid}/alerts/{aid}/ack —
{"actor": "…"}
Operations (maker-checker)
An operation is a request to an agency. Lifecycle:
pending_approval ──approve×N──► approved ──execute──► executing ──► executed | failed
└──return──► returned pending_approval/approved ──cancel──► cancelled
The payload is encrypted and hashed at creation; approvers approve the hash they saw, and execution sends the same payload. An api channel that is not ready refuses at creation with 409 channel_not_ready.
POST /v1/tenants/{tid}/operations
{"external_ref": "erv-2026-0091", "op": "exit_reentry.issue", "created_by": "user:12",
"payload": {"employee_id": "…", "return_by": "2026-12-20"}}
| op | payload |
|---|---|
contract.submit | employee_id, start_date, end_date? |
iqama.renew | employee_id, months (1–60, default 12) |
exit_reentry.issue | employee_id, return_by |
exit_reentry.extend | visa_ref, return_by |
exit_reentry.cancel | visa_ref |
final_exit.issue | employee_id, leave_by? |
final_exit.cancel | visa_ref |
POST /v1/tenants/{tid}/wps/runs — builds the WPS wages file per the HRSD specification and creates a wps.submit operation.
{"external_ref": "wps-2026-11", "created_by": "user:12", "period": "2026-11",
"file_ref": "WPS202611A", "value_date": "2026-11-27", "debit_date": null,
"lines": [{"employee_ref": "emp-301", "basic": "6000.00", "housing": "1500.00",
"other_earnings": "0.00", "deductions": "0.00", "description": "…"}]}
Rules enforced: net = basic + housing + other − deductions (> 0); header total = sum of lines; file_ref ≤16 alphanumerics and unique per establishment; value date not before today; debit date between today and value date; ID starts with 1 or 2; no duplicate employee; names in the file's single language; comma decimal separator in the file. The bank signs the processed file — the gateway does not.
- GET /v1/tenants/{tid}/operations?status=&agency= · GET /v1/operations/{oid} (summary, approvals, result)
- POST /v1/operations/{oid}/approve —
{"approver_ref": "user:57", "payload_sha256": "…", "note": "…"} - POST /v1/operations/{oid}/return —
{"approver_ref": "…", "note": "required"}(voids approvals) - POST /v1/operations/{oid}/cancel —
{"actor": "…", "reason": "…"} - POST /v1/operations/{oid}/execute —
{"executed_by": "…"}. Result:file→{"manual": true, "instructions_ar": …}(do it on the agency portal, then record the status);sandbox→{"reference": "SANDBOX-…", "simulated": true}. - GET /v1/operations/{oid}/file — WPS file bytes, only after approval. Headers
X-File-SHA256,X-Simulated. - GET /v1/operations/{oid}/audit
Audit
- GET /v1/tenants/{tid}/audit — hash-chained log for the establishment.
- GET /v1/tenants/{tid}/audit/verify —
{"ok": true, "entries": n, "head": "…"}or{"ok": false, "broken_at_seq": n}.
Webhooks
POST /v1/webhook — {"url": "https://…"} returns the signing secret once.
Events: obligation.updated, alert.raised, operation.updated. Headers: X-Octa-Event, X-Octa-Delivery, X-Octa-Timestamp (ms), X-Octa-Signature = hex HMAC-SHA256 of {timestamp}.{raw body}. Reject if the timestamp is older than 5 minutes. Retries: 1 min, 5 min, 15 min, 1 h, 6 h. Payloads never contain ID numbers or IBANs.
{"event": "alert.raised", "tenant_id": "…", "tenant_ref": "hospital-12",
"alert": {"code": "iqama_expiry:2026-12-09:d30", "level": "warning", "message_ar": "…", "due_date": "2026-12-09"}}
Agencies
GET /v1/agencies — public profiles: modes, published facts with source links, and pending_fields (everything still awaiting the agency's own documentation). api_ready is false for all agencies in this version.
Subscriptions
Billing unit: one establishment with at least one non-sandbox channel. Prices come from the owner's pricing.json (GET /portal/plans); without it plans show "contact us". Provisioning after payment on the OCTA site uses POST /provision and POST /billing/webhook (HMAC on {timestamp}.{body}, 5-minute window) — the same contract as the ZATCA gateway.
Python client
clients/octa_gov_client.py — depends only on requests; rejects floats before sending; GovGatewayError.code == "channel_not_ready" for channels awaiting documentation; verify_webhook(secret, headers, raw_body).