Connect your system with the HR system through a secure API

Ready-made API endpoints to connect accounting, payroll and reporting systems with employee, voucher, expense and payroll data. Each token is tied to a specific company and tenant to ensure complete data isolation.

Quick request example

Use the Bearer Token issued from the dashboard.

curl -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Accept: application/json" \ https://hr.almutawir.sa/api/v1/hr/employees

Integration in 4 steps

Each tenant creates their own token from the dashboard, then uses it in their external system.

1. Create the token

  • Open the dashboard
  • Open the API Integration page
  • Choose the required permissions
  • Copy the token right away because it is shown only once

2. Authentication

  • Send the token in the Header
  • Format: Authorization: Bearer TOKEN
  • Each token is tied to a company and tenant
  • A token can be disabled or regenerated

3. Pull data

  • Pull employee data
  • Pull general vouchers and employee vouchers
  • Pull expenses and payroll
  • Use filters and pagination

4. Integrate the external system

  • Connect the accounting system
  • Set up periodic sync
  • Handle result pages
  • Record the last sync
Do not put the token in the front end or public JavaScript. It must be used from the backend server only.

Authentication

All protected requests need a header named Authorization.

Authorization: Bearer YOUR_API_TOKEN Accept: application/json

curl -s \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Accept: application/json" \ "https://hr.almutawir.sa/api/v1/company"

Available API endpoints

The following endpoints are ready to connect with external systems.

Method Path Description Main filters
GET /api/v1/health API health check -
GET /api/v1/company Company/tenant data linked to the token -
GET /api/v1/hr/employees Employee list search, status, department, iqama_expiring, iqama_expired, per_page
GET /api/v1/hr/employees/{id} Employee details with documents -
GET /api/v1/accounting/summary Financial and operational summary -
GET /api/v1/accounting/vouchers General vouchers and employee vouchers party_type, type, status, from, to, per_page
GET /api/v1/accounting/expenses Expenses status, category, from, to, per_page
GET /api/v1/accounting/payrolls Payroll runs status, month, per_page

Key variables and fields

These are the most commonly used fields when integrating with accounting and HR systems.

Employees

  • id: internal employee ID
  • employee_no: employee number
  • full_name: employee name
  • iqama_number: iqama number
  • iqama_expiry_date: iqama expiry date
  • job_title: job title
  • department: department
  • status: employee status

Vouchers

  • voucher_no: voucher number
  • type: receipt or payment
  • party_type: general or employee
  • amount: voucher amount
  • voucher_date: voucher date
  • status: voucher status
  • payment_method: payment method

Expenses

  • expense_number: expense number
  • title: expense title
  • category: category
  • amount: amount
  • expense_date: expense date
  • status: pending, approved or rejected
  • vendor_name: vendor

Payroll

  • month: payroll month
  • title: payroll title
  • status: draft, approved or paid
  • total_amount: payroll total
  • payment_date: payment date
  • items: employee line items within the payroll

Practical examples

Ready-made samples the tech team can use directly.

Pull the first 10 employees

curl -s \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Accept: application/json" \ "https://hr.almutawir.sa/api/v1/hr/employees?per_page=10"

Search for an employee

curl -s \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Accept: application/json" \ "https://hr.almutawir.sa/api/v1/hr/employees?search=Mohammed"

Approved employee vouchers

curl -s \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Accept: application/json" \ "https://hr.almutawir.sa/api/v1/accounting/vouchers?party_type=employee&status=approved"

Accounting summary

curl -s \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Accept: application/json" \ "https://hr.almutawir.sa/api/v1/accounting/summary"

Response format

All responses are returned in JSON format to make integration easier.

{ "success": true, "data": { "current_page": 1, "data": [ { "id": 68, "employee_no": "EMP-001", "full_name": "Employee name", "iqama_number": "0000000000", "job_title": "Accountant", "department": "Finance", "status": "active" } ], "per_page": 10, "total": 1 } }
All results are isolated by the company or tenant linked to the token. The external system cannot access another company's data.