Connect Mihnaro to your AI assistant

Who you are, which company and modules you can use, your language and look, and the AI apps connected to your account.

Try asking: «Who am I in Mihnaro?» «Which AI apps are connected to my account?»

• account_deletion Changes data

  The signed-in person's request to delete their Mihnaro account and data (docs/account-deletion.md), as GET/POST /api/v1/app/me/deletion-request. action "status" lists their requests; "request" asks for deletion (optional reason): HR of each of their companies and the Mihnaro team are told. A pending request is returned instead of a new one.

  Needs: No single permission: it follows your role and branches

  Parameters: action* reason * = required

• company_connected_apps Can delete

  The AI apps people connected to this company (integrations.ai_apps.manage). action list: each connection with its person and last use. action revoke: grant_id; the app stops at once and its owner is told. Confirm before revoking. docs/ai-integrations.md.

  Needs: employees.view_sensitive

  Parameters: company_id* action grant_id * = required

• get_app_brand Reads only

  The main brand the Mihnaro mobile app is built with (docs/mobile-app.md, GET /api/v1/app/brand): the brand navy and teal from the admin panel, the logo and mark (dark and white), the app icon sources (an uploaded square icon, else the mark) and a version that changes when any of it does.

  Needs: No single permission: it follows your role and branches

• get_app_branding Reads only

  What the Mihnaro mobile app is painted with (docs/mobile-app.md): the system palette (primary, secondary, sidebar, login panel) and logos from the admin panel, and the addresses single sign-on may return to. A company's own logo is in get_company_context.

  Needs: No single permission: it follows your role and branches

• get_company_context Reads only

  For one company of the signed-in user: the modules its license includes, the license dates, and the branches this user can work in.

  Needs: No single permission: it follows your role and branches

  Parameters: company_id* * = required

• get_map_tiles Reads only

  Where the app's maps take their pictures from: the tile address, its attribution and the highest zoom. For anyone signed in, the same as GET map-tiles.

  Needs: No single permission: it follows your role and branches

• list_my_connected_apps Reads only

  The AI apps connected to the signed-in person's account and their access tokens for AI apps: id, kind (oauth or token), name, company, when connected and last used. Token values are never shown. docs/ai-integrations.md.

  Needs: No single permission: it follows your role and branches

• manage_my_connected_app Can delete

  Disconnect one of the signed-in person's own AI apps (kind oauth) or revoke one of their access tokens (kind token): id and kind from list_my_connected_apps. Anything using it stops at once; if it is the app making this call, this connection ends too. Confirm first. docs/ai-integrations.md.

  Needs: No single permission: it follows your role and branches

  Parameters: id* kind* * = required

• manage_my_list_columns Changes data

  Show / hide columns of a list for the signed-in user (saved on the account, same on every device). Lists: salaries, salary_batches, transactions, transactions_off_cycle, overtimes, loans, and requests.<type> for My Requests per request type. action get: one list (list) or all, with each column's key, label and visible. action set: list and hidden (column keys to hide; empty shows them all).

  Needs: No single permission: it follows your role and branches

  Parameters: action* list hidden * = required

• manage_my_push_tokens Changes data

  The phones the signed-in person gets push notices on through the Mihnaro mobile app (docs/mobile-app.md). action list: the phones (tokens shortened, provider fcm | apns | expo, active, disabled_reason). action register: token (the phone's native FCM registration token or APNs device token; Expo tokens are refused), platform (ios or android), provider (fcm or apns, defaults from the platform), device_name, apns_environment (production or sandbox, which of Apple's servers this build uses, if known). action forget: token, to stop pushes to that phone. Notices that reach the bell are pushed straight to Google/Apple for every active phone.

  Needs: No single permission: it follows your role and branches

  Parameters: action* token platform provider device_name apns_environment * = required

• manage_my_system_announcements Changes data

  Messages from the Mihnaro team for the signed-in person (docs/platform-control.md). action list: the ones still open on a channel (web or app, default web), in the person's language. action dismiss: close one (id) that may be dismissed. action acknowledge: confirm reading one (id) that must be acknowledged.

  Needs: No single permission: it follows your role and branches

  Parameters: action* id channel * = required

• update_my_preferences Changes data

  Set the signed-in user's own language (en or ar) and theme (light, dark or system). Saved on the account, so it applies on every device. Only the fields given change.

  Needs: No single permission: it follows your role and branches

  Parameters: locale theme * = required

• whoami Reads only

  The signed-in company user and the companies they belong to, with whether each can be accessed now.

  Needs: No single permission: it follows your role and branches

Employee records and files, branches, departments, positions, projects, documents, sign-in accounts, imports and the company's own settings.

Try asking: «How many employees are in the Basra branch?» «Show Sara's job history»

• add_org_level Changes data

  Add a missing organization level (department, section, work location…) while filling an employee's job details, as the employee page does. Needs structure.manage, and the employee's branch (or, for a new hire, the branch worked in) must allow adding organization levels from the employee page.

  Needs: structure.manage

  Parameters: company_id* type* name* parent_id employee_id * = required

• archive_employee Changes data

  "Delete" an employee: the record is archived, never deleted. It leaves the lists, headcount, payroll runs, approvals and fingerprint devices and the person can no longer sign in; attendance, payslips, requests, documents and history stay linked. Its number stays reserved. Not the same as terminate_employee (end of service). Undo with restore_employee. Needs employees.archive.

  Needs: employees.archive

  Parameters: company_id* employee_id employee_number branch_id reason * = required

• assign_to_project Changes data

  Assign an employee to a project, or change their assignment: job role (position), contribution percentage, staff code, dates.

  Needs: projects.manage

  Parameters: company_id* project_id* employee_id* position_id contribution_percent staff_code start_date end_date * = required

• company_limits Changes data

  The company's file sizes, counts and lengths (docs/limits.md), as /api/v1 settings/limits. action read (limits.view): each limit with its company, branch and platform values, the value in force and the server's ceiling for files. action update (limits.manage): values {key: number, or null to go back to the level above}, sizes in KB; only the keys sent change. branch_id: one branch's own values.

  Needs: employees.view_sensitive

  Parameters: company_id* action branch_id values * = required

• delete_document Can delete

  Delete a document and its files (by id from list_documents). Allowed for whoever uploaded it, HR for employees in their scope, and company-wide HR for company documents.

  Needs: employees.view_sensitive

  Parameters: company_id* document_id* * = required

• delete_employee_file_record Can delete

  Remove a contract, bank account, family member or document from an employee's file (its files are deleted too).

  Needs: employees.manage

  Parameters: company_id* employee_id* kind* record_id* * = required

• delete_org_unit Changes data

  Delete an unused unit of the organization structure. Refused while any employee (former ones included) is in it, a section hangs under it, or anything else still uses it: turn it off with save_org_unit (is_active false) instead.

  Needs: structure.manage

  Parameters: company_id* unit_id* * = required

• employee_accounts Changes data

  Employees' sign-in accounts (employees.manage, in my scope; docs/company-management.md). action existing_users: ZenHR's "Add Employee for an Existing User" list, the ended records (latest per person) to rehire with rehire_employee and company accounts with no employee record (q searches number, name, email). action temporary_password: employee_id with temporary_password (the company's password policy); they must change it after signing in; never the owner's or your own account. action unlock: employee_id, unlocks an account locked by failed sign-in attempts.

  Needs: employees.manage

  Parameters: company_id* action* employee_id temporary_password q * = required

• get_branch_context Reads only

  The branch workspace the tools work in for this company: the current branch (or all_branches), whether "all" may be chosen, and the branches this user may switch to. Every other company tool shows only the current branch's data; pass branch (a branch id or "all"; in_branch where a tool already uses branch as a filter) to a tool, or the X-Branch header, to use another branch for one call.

  Needs: employees.view_sensitive

  Parameters: company_id* * = required

• get_company_settings Reads only

  System preferences → Account setup: company names, address, phone, email, logo, currency, working hours and grace, weekend days (0 = Sunday), end-of-service days and minimum years, org chart type (company or branch) and whether only HR sees it; and mail_server, the company's own mail server (its password is never returned, and it is changed only on the screen or the API), with employee_emails: whether "Email employees" is on (docs/mail.md).

  Needs: settings.manage

  Parameters: company_id* * = required

• get_e_signature_image Reads only

  The picture of one of the company's e-signatures (list_employee_settings kind e_signatures gives the ids), as GET /api/v1/app/companies/{id}/employee-settings/e_signatures/{id}/image. Needs employee_settings.e_signatures.manage or letters.manage. Returns filename, mime, size and the image as base64.

  Needs: letters.manage

  Parameters: company_id* id* * = required

• get_employee Reads only

  One employee record, by employee_id or by employee_number (the number people use; add branch_id when numbers repeat across branches). Archived records are found too (archived: true).

  Needs: employees.view

  Parameters: company_id* employee_id employee_number branch_id * = required

• get_employee_history Reads only

  An employee's job history: hired, changes (department, position, grade, manager...), transfers and end of service, with dates and readable lines; and their dated professional data records.

  Needs: employees.view

  Parameters: company_id* employee_id* * = required

• get_employee_numbering Reads only

  How the company numbers its employees: prefix, padding (digits), next_number, scope (numbers unique across the company or per branch), allow_reuse (whether archived and ended numbers may be given again), and per branch its own numbering, the highest number used and the number its next employee gets. Needs employee_settings.manage.

  Needs: employee_settings.manage

  Parameters: company_id* * = required

• get_my_profile Reads only

  My profile in a company: my name, email, username, roles, and my employee record (number, job, department, branch, manager, hire date). To change my password use the API (PUT /api/v1/app/me/password).

  Needs: employees.view_sensitive

  Parameters: company_id* * = required

• get_org_chart Reads only

  The org chart: who reports to whom, as nested trees (one for the company, or one per branch if the company set it so). Each person has "reports". Filters (ZenHR's): department, branch, job_role, work_location, section, project, hierarchy_group, business_unit, division, segment (ids), work_type, q (name or number). Hidden from non-HR when the company hides the org structure.

  Needs: employees.view self.org_chart

  Parameters: company_id* department branch job_role work_location section project hierarchy_group business_unit division segment work_type q * = required

• get_regional_settings Reads only

  Regional settings (date and time format, calendar, Arabic month names, first day of the week, numerals, separators, currency display; docs/regional-settings.md). mine=true: my effective formats (my branch, else the company, else the platform) with English and Arabic samples, for anyone in the company. Otherwise the company defaults, the choices with their labels, and every branch's own values (null = follows the company), effective values and where each comes from (needs settings.manage or branches.manage). Same as GET /api/v1/app/companies/{id}/me/locale and …/regional-settings.

  Needs: branches.manage settings.manage

  Parameters: company_id* mine * = required

• get_termination_check Reads only

  Leaving (docs/terminations.md, employees.terminate). With employee_id: the background check before terminate_employee (pending_count; who to substitute as direct manager, supervisor, approver or key staff; pending requests; loans still owed; assets held) with contracts, insurance and cost centers for information, and the end-of-service estimate today for each termination type. Without employee_id: the leaving records of the employees in scope.

  Needs: employees.terminate

  Parameters: company_id* employee_id * = required

• import_rows Changes data

  Import data from rows: each row is an object of field → value (fields from list_importers). Without commit it only checks every row and lists the problems; with commit=true it saves all rows, or none if anything is wrong. New employees get sign-in accounts; their temporary passwords are returned once.

  Needs: employees.view_sensitive

  Parameters: company_id* type* rows* mode commit options * = required

• invite_employees Changes data

  Invite current employees without a sign-in account to the app (employees.manage, docs/attendance.md §13), by branch_id and department_id, channel email or whatsapp. Without send it only previews: how many would be invited, how many are skipped and why (has_account, invited_recently, no_email, no_mobile, email_in_use, emails_off = "Email employees" is held for the company or branch, docs/mail.md) and a masked sample. send true with expected (the previewed count) queues the messages, 20 a minute, one batch per company at a time. Only send when the person asked to send.

  Needs: employees.manage

  Parameters: company_id* channel* branch_id department_id send expected * = required

• list_company_branches Reads only

  The company's branches with their logos, the license's max_branches and whether another can be added.

  Needs: branches.manage

  Parameters: company_id* * = required

• list_company_users Reads only

  User setup: the company's accounts with username, roles and where each applies, and status (active or inactive). Filter by q (name, email, username), role id, status.

  Needs: users.manage

  Parameters: company_id* q role position status * = required

• list_directory Reads only

  The company directory: active colleagues with their job, department, branch and work contact details (email, phone, extension). Open to everyone in the company. Search by name, job or email.

  Needs: employees.view self.directory.view

  Parameters: company_id* q department branch page * = required

• list_documents Reads only

  Documents: my file and company documents for everyone; HR (employees.view_sensitive) also sees employees' files in their scope and the ones expired or expiring soon. tab: all, my, employees, company.

  Needs: employees.view_sensitive self.documents.view

  Parameters: company_id* tab employee category page * = required

• list_employee_file Reads only

  One section of an employee's file: contracts, bank_accounts, family or documents. Bank accounts and documents need employees.view_sensitive. Files themselves are downloaded through the app or the API.

  Needs: employees.view employees.view_sensitive

  Parameters: company_id* employee_id* kind* * = required

• list_employee_settings Reads only

  The lists behind the employee file: contract_types, job_grades, document_types, custom_fields, org_levels or field_rules.

  Needs: employee_settings.manage

  Parameters: company_id* kind* * = required

• list_employees Reads only

  Employee records, 25 per page. status: current (default, not terminated), active, suspended, terminated, all, or archived (archived records only; every other status leaves them out). search matches number, name or email; employee_number matches exactly. Also the license headcount.

  Needs: employees.view

  Parameters: company_id* status employee_number salary_status branch_id search page * = required

• list_importers Reads only

  Import data: the kinds of data that can be imported (employees, quick employees, family members, contracts, bank accounts, custom fields) with their fields, the importers coming with later modules, and the last imported sheets. With type: that importer's template rows (the CSV template: headers then examples; language en|ar; existing true fills it with the current data). Needs company-wide employees.manage and employees.view_sensitive.

  Needs: employees.manage employees.view_sensitive

  Parameters: company_id* type language existing * = required

• list_org_units Reads only

  The organization structure: work locations, departments, sections (with their department as parent_id), projects and hierarchy groups. branch_id null means all branches.

  Needs: structure.manage

  Parameters: company_id* type * = required

• list_positions Reads only

  The company's job titles (positions).

  Needs: positions.manage

  Parameters: company_id* * = required

• list_projects Reads only

  The company's projects (code, names, client, group and entity codes, manager, dates, budget hours, active or closed). Give project_id for one project with the employees assigned to it and its hours from the timesheets (approved, waiting, labour cost, budget used, by employee and month).

  Needs: projects.manage

  Parameters: company_id* project_id * = required

• list_setup_form Reads only

  Setup forms (ZenHR full forms): the items of one entity with their fields, and the fields' kinds and options. Entities now: org-levels (organizational levels: type, parent, rank, subsidiary ID, logo, key staff) and attendance-functions (functions such as breaks and visits: deduct per, minutes per day, per transaction and in total, active).

  Needs: employees.view_sensitive

  Parameters: company_id* entity* * = required

• manage_checklist Changes data

  Joining and leaving checklists (docs/terminations.md). action overview (employees.view: joiners and leavers in scope with their progress; fields type onboarding|offboarding, status not_started|in_progress|completed, default not completed). employees.manage over the employee: show (employee_id: the steps), add (employee_id; fields type, title {en, ar}), toggle (item_id: tick a step off or back on), delete (item_id). The standard steps are the setup list checklist-templates (save_setup_form_item).

  Needs: employees.manage employees.view

  Parameters: company_id* action* employee_id item_id fields * = required

• rehire_employee Changes data

  ZenHR's "Add Employee for an Existing User": a new employee record for someone whose record has ended (employee_id = the ended record). Personal and contact data and the sign-in account carry over; hire_date is required and comes after the last working day; branch_id, employee_number, position_id, units, manager_id, work_type, contract_type_id, contract_end_date and probation_end_date set the new job. copy_bank_accounts and copy_family (default true) copy those. Counts against the license.

  Needs: employees.manage

  Parameters: company_id* employee_id* hire_date* branch_id employee_number position_id work_location_id department_id section_id project_id manager_id work_type contract_type_id contract_end_date probation_end_date copy_bank_accounts copy_family * = required

• remove_project_assignment Can delete

  Take an employee off a project (by assignment id from list_projects).

  Needs: projects.manage

  Parameters: company_id* assignment_id* * = required

• resolve_termination Changes data

  Resolve an item of the termination check, or cancel a termination (docs/terminations.md, employees.terminate over employee_id). action substitute (fields kind approvers|manager|supervisor|key_staff, substitute_id: an employee who takes the leaver's place), withdraw_requests (every pending request), take_asset (fields asset_id), expire_insurance (fields insurance_id), pay_loans (each remaining loan amount repaid in cash), deduct_loans (left for the final settlement; needs the legal rule validated), cancel_termination (undo a termination entered by mistake, before payroll paid the final settlement). Returns the check after the change.

  Needs: employees.terminate

  Parameters: company_id* employee_id* action* fields * = required

• restore_employee Changes data

  Brings an archived employee back as it was, with its number. Refused when another current employee now has that number, the subscription is full, or the person already has a current record. Find archived records with list_employees status=archived. Needs employees.archive.

  Needs: employees.archive

  Parameters: company_id* employee_id employee_number branch_id * = required

• save_branch Changes data

  Add a branch (without branch_id) or change one. New branches stay within the license. Country sets the default currency and timezone. Logos are uploaded in the app or with multipart POST to the API.

  Needs: branches.manage

  Parameters: company_id* branch_id name code country currency timezone is_active * = required

• save_company_settings Changes data

  Change System preferences → Account setup. Send only what changes; the rest stays. The logo is uploaded on the screen or the API, not here (remove_logo works).

  Needs: settings.manage

  Parameters: company_id* company_name_en company_name_ar company_address company_phone company_email currency work_start work_end late_grace_minutes weekend_days eos_days_per_year eos_min_years org_level_type hide_org_chart secure_documents remove_logo * = required

• save_employee Changes data

  Add (without employee_id) or change an employee record. New employees count against the license across all branches. create_login: true makes a sign-in account from the work email and returns a temporary password once. Use transfer_employee to change branch.

  Needs: employees.view_sensitive

  Parameters: company_id* employee_id employee_number name email personal_email phone hire_date branch_id status position_id work_location_id department_id section_id project_id manager_id create_login name_parts gender birth_date marital_status nationality national_id passport_number job_title work_type job_grade_id contract_type_id supervisor_id probation_end_date change_effective_date custom_fields * = required

• save_employee_file_record Changes data

  Add (without record_id) or change a contract, bank account or family member in an employee's file. Bank accounts need employees.view_sensitive; their shares can't pass 100%. Documents need a file, so upload them through the app or the API.

  Needs: employees.manage employees.view_sensitive

  Parameters: company_id* employee_id* kind* record_id fields * = required

• save_employee_numbering Changes data

  Changes the employee numbering. Without branch_id: the company's prefix, padding, next_number, scope (company or branch) and allow_reuse; changing scope to company is refused while current employees of different branches share a number. With branch_id: that branch's own numbering (custom true with prefix, padding, next_number) or back to the company's (custom false). Numbers already given never change. Returns get_employee_numbering. Needs employee_settings.manage.

  Needs: employee_settings.manage

  Parameters: company_id* branch_id custom prefix padding next_number scope allow_reuse * = required

• save_employee_setting Changes data

  Add (without record_id) or change an entry in one of the employee file lists (contract_types, job_grades, document_types, custom_fields, org_levels, field_rules, e_signatures, banks). Names are {"en","ar"}; list custom fields need options [{"en","ar"}]. Document types take applies_to (employees|company|both), is_default, deletable, has_expiry and notify_before (week|2_weeks|month|2_months|3_months|6_months: how long before expiry HR is told); custom fields take field_level (personal|professional|financial|bank_account: bank_account fields are asked on each bank account); custom fields take group_name {"en","ar"} (ZenHR Manage Additional Info); field rules take allow_numbers/allow_lowercase/allow_uppercase/allow_special (false = not allowed); e_signatures take signer_title, user_id and image_base64 (a PNG/JPG data URL).

  Needs: employee_settings.manage

  Parameters: company_id* kind* record_id name field applies_to notify_before group_name image_base64 country branches external_ref * = required

• save_org_unit Changes data

  Add (without unit_id) or change a unit of the organization structure. A section needs parent_id (its department). branch_id ties a unit to one branch.

  Needs: structure.manage

  Parameters: company_id* unit_id type name code establishment_number branch_id parent_id is_active subsidiary_id establishment_name governance_location ss_number tax_number address po_box * = required

• save_position Changes data

  Add (without position_id) or change a job title (job role): name, code, active, type (regular or hazardous), available across all branches, job description.

  Needs: positions.manage

  Parameters: company_id* position_id name code is_active job_role_type company_level job_description * = required

• save_professional_data Changes data

  A dated professional data record for an employee: new job role (position), units, manager, supervisor, work type or outsourced, from effective_on (and until expires_on, after which the old values come back). Applied now if the date has come, otherwise on its date. Send only what changes; notes are ZenHR's Notes. Or cancel a future record with cancel_record_id; edit a record with update_record_id (a future one as it is, or the one in effect: ZenHR's "Update Current Professional Info", no new dated record); delete one with delete_record_id (the one in effect puts back what it replaced).

  Needs: employees.manage

  Parameters: company_id* employee_id cancel_record_id update_record_id delete_record_id notes effective_on expires_on notify_employee position_id work_location_id department_id section_id project_id hierarchy_group_id business_unit_id division_id segment_id work_type manager_id supervisor_id employee_kind * = required

• save_project Changes data

  Add a project, or edit one with project_id (send only what changes). Code is unique; names in Arabic and English are required; status is active or closed.

  Needs: projects.manage

  Parameters: company_id* project_id code name client group_name group_code entity_code manager_id start_date end_date budget_hours status * = required

• save_regional_settings Changes data

  Change regional settings (docs/regional-settings.md). Without branch_id: the company defaults (settings.manage). With branch_id: that branch's own values (branches.manage), and also its country and timezone. Only the keys given change; null or "" goes back to the level above (branch → company → platform). Display only: no stored date or amount changes. The change is in the activity log and the company's admins are notified. Values: date_format j M Y | d/m/Y | Y-m-d | d-M-Y | j F Y | l j F Y | F j, Y | M j, Y | m/d/Y | d.m.Y; time_format 12 | 24; week_start saturday … friday; calendar gregorian | gregorian_hijri; month_names levant (كانون الثاني… تشرين الثاني) | gulf (يناير… نوفمبر); numerals latn | arab; thousands_separator comma | dot | space | arabic_thousands | none; decimal_separator dot | comma | arabic_decimal; currency_display name | code | symbol; currency_position after | before.

  Needs: branches.manage settings.manage

  Parameters: company_id* branch_id date_format time_format week_start calendar month_names numerals thousands_separator decimal_separator currency_display currency_position country timezone * = required

• save_setup_form_item Changes data

  Add (without id) or change (with id, send only what changes) an item of a setup form, with name {"en","ar"} and the entity's fields from list_setup_form. Files (logo) are uploaded on the screen or the API. With delete=true and id, deletes it unless it is in use.

  Needs: employees.view_sensitive

  Parameters: company_id* entity* id name delete level_type parent_id rank subsidiary_id key_staff country active * = required

• send_company_test_email Changes data

  Settings → Email server → "Send a test email" (settings.manage, docs/mail.md): one test email through the company's own mail server. A failure says why in plain words (wrong username or password, connection refused, encryption and port mismatch…). Only send when the person asked for a test.

  Needs: settings.manage

  Parameters: company_id* to* * = required

• set_employee_emails Changes data

  Settings → Email server → "Email employees" (settings.manage, docs/mail.md): on lets the company email its people (invitations, welcome emails, notices, reminders); off holds them (notices still reach the bell; password resets and candidate emails are not held). Kept per branch like the reminders: branch_id for one branch, else the branch being worked in (the main branch's value is the company's). Only change it when the person asked.

  Needs: settings.manage

  Parameters: company_id* on* branch_id * = required

• set_main_branch Changes data

  Make an active branch the company's main one (owners land on it).

  Needs: branches.manage

  Parameters: company_id* branch_id* * = required

• set_user_status Changes data

  User setup: switch a company account on (active) or off (inactive). An inactive user can't work in this company. Not for yourself or the company admin.

  Needs: users.manage

  Parameters: company_id* user_id* status* * = required

• switch_branch Changes data

  Switches the branch workspace (like the branch switcher in the app header): a branch id, or "all" for every branch (company-wide roles only). Remembered for the web app, the API and later tool calls.

  Needs: employees.view_sensitive

  Parameters: company_id* branch* * = required

• terminate_employee Can delete

  End an employee's service. The record is kept, stops counting against the license, and the person can't sign in any more (unless they are the owner). It is refused while the termination check (get_termination_check) has pending items; then the leaving record is kept, the offboarding checklist starts, and HR, the manager and key staff are told as Notifications setup says.

  Needs: employees.terminate

  Parameters: company_id* employee_id* terminated_on* termination_type* note termination_reason_id custom_fields * = required

• transfer_employee Changes data

  Move an employee to another branch: the old record ends (transfer) on effective_date and a new one starts there with the same number, hire date and sign-in. Returns the new record.

  Needs: employees.transfer

  Parameters: company_id* employee_id* branch_id* effective_date* position_id work_location_id department_id section_id project_id note * = required

Who may do what: roles, their assignment, permission groups, exceptions for a person, and an explanation of why something is open or closed.

Try asking: «What can I do in this company?» «Why can't Ali see payroll?»

• assign_role Changes data

  Give a role to a current employee who has a sign-in account, in a scope: company, branch (scope_id = branch id), department, work_location, section, project, hierarchy_group, business_unit, division or segment (scope_id = that unit's id), reports (the person's own reports) or reports_of (scope_id = an employee whose reports it covers).

  Needs: roles.manage

  Parameters: company_id* employee_id* role_id* scope* scope_id * = required

• delete_permission_group Changes data

  Delete a group: its people lose what its seats gave them. As DELETE permission-groups/{id}. Needs roles.manage.

  Needs: roles.manage

  Parameters: company_id* group_id* * = required

• delete_permission_override Changes data

  Take off one person's exception. As DELETE permission-overrides/{id}. Needs roles.manage.

  Needs: roles.manage

  Parameters: company_id* override_id* * = required

• delete_role Can delete

  Delete a role; everyone who had it loses it.

  Needs: roles.manage

  Parameters: company_id* role_id* * = required

• explain_access Reads only

  Why is this open? For one person and one permission, on the web and in the app: open or closed, and what makes it so (owner, personal exception, role and scope, or group seat). As GET people/{user}/access/explain. Needs roles.manage.

  Needs: roles.manage

  Parameters: company_id* user_id* permission* * = required

• get_my_access Reads only

  What the signed-in person may open in a company, as the mobile app uses it: the licensed modules, each permission with its scope ("company" or the branches, departments and reports it covers), and the features that follow (clock, attendance, leaves, requests, payslips, approvals, directory, documents, tasks, announcements, notifications), and clock_channels (the branch setting "Clocking from": both, web or mobile; clock is false for web-only). The same as GET me/access.

  Needs: employees.view_sensitive

  Parameters: company_id* * = required

• get_my_permissions Reads only

  What the signed-in user may do in a company and where: each permission (sub-module permissions included, also when they come with their module permission) with "company" or the branches, departments and reports it covers. Owners have everything.

  Needs: employees.view_sensitive

  Parameters: company_id* * = required

• get_person_access Reads only

  See as them: every permission a person has on the web and in the app, each field's level (about_employee_id for one employee), and their exceptions. As GET people/{user}/access. Needs roles.manage.

  Needs: roles.manage

  Parameters: company_id* user_id* about_employee_id * = required

• list_permission_groups Reads only

  The company's groups: who is in each (branches, units, named people) and the role of its three seats (manager, team leader, employee). As GET permission-groups. Needs roles.manage.

  Needs: roles.manage

  Parameters: company_id* * = required

• list_permission_overrides Reads only

  Exceptions for people: an action opened or closed, or a field's level, per channel. Filter by user_id. As GET permission-overrides. Needs roles.manage.

  Needs: roles.manage

  Parameters: company_id* user_id * = required

• list_role_assignments Reads only

  Who has which role in which scope. Filter by user_id or role_id.

  Needs: roles.manage

  Parameters: company_id* user_id role_id * = required

• list_roles Reads only

  The company's roles with their permissions and how many people have each, plus the permission catalog (each group's permissions, and under children the sub-module permissions that can be given alone; a module permission grants all its children), scopes and presets; catalog lists every permission flat with its group, module permission, scopes and English and Arabic labels; line_manager_access is what direct managers may do for their reports (set_line_manager_access).

  Needs: roles.manage

  Parameters: company_id* * = required

• remove_role_assignment Can delete

  Take a role away from someone (by assignment id from list_role_assignments).

  Needs: roles.manage

  Parameters: company_id* assignment_id* * = required

• role_matrix Changes data

  Read a role's table of web and app switches for every action and of web and app levels for every field. Send actions {"key": {"web": true, "app": false}} or fields {"entity.field": {"web": "edit", "app": "hidden"}} to change those rows; the rest stays. Company setup keys (setup.*) are closed on the app until opened here.

  Needs: employees.view_sensitive

  Parameters: company_id* role_id* actions fields * = required

• save_permission_group Changes data

  Add (without group_id) or change a group. Members: branch_ids narrow it, unit_rules ({"department": [ids], "work_location": [ids]…}) and people (employee ids) fill it. Seats: manager_role_id reaches everyone under a registered manager inside the group, team_leader_role_id a registered supervisor's direct team inside the group, employee_role_id each member themselves. As POST and PATCH permission-groups. Needs roles.manage.

  Needs: roles.manage

  Parameters: company_id* group_id name description is_active branch_ids unit_rules people manager_role_id team_leader_role_id employee_role_id * = required

• save_permission_override Changes data

  Set one person's exception. kind action: subject is a permission key, web and app are open, closed or null (no exception there); closed beats every role and group. kind field: subject is a field (employee.basic_salary…), web and app are hidden, view, edit or null. Both null takes it off. As POST permission-overrides. Needs roles.manage.

  Needs: roles.manage

  Parameters: company_id* user_id* kind* subject* web app scope scope_id reason * = required

• save_role Changes data

  Add (without role_id) or change a role. permissions are keys from list_roles, module permissions or sub-module ones (leaves.adjustments.manage…); preset (hr_manager, branch_manager, line_manager) fills a new role. is_active false switches a role off: its people keep it but it grants nothing until switched on.

  Needs: roles.manage

  Parameters: company_id* role_id name description permissions channels fields is_active preset * = required

• set_line_manager_access Changes data

  Turn on or off what direct managers may do for the people who report to them, with or without a role: lm_rate_competencies, lm_assess_potential, lm_salary_adjustments, lm_team_suspensions. Keys left out keep their value. Needs roles.manage.

  Needs: roles.manage

  Parameters: company_id* lm_rate_competencies lm_assess_potential lm_salary_adjustments lm_team_suspensions * = required

Your own attendance and schedule, the team's records, shifts, timesheets, missing punches, clocking security and its reviews.

Try asking: «Show today's attendance» «Who was late this week?»

• act_on_attendance_recommendations Changes data

  Look at attendance again (action refresh, with from and to; the last month by default, three months at most), or act on pending recommendations by ids: ignore, notify (tell the direct manager) or apply (an absence becomes leave of leave_type_id; time taken from the leave type attendance setup names; overtime and salary deductions come with requests and payroll).

  Needs: employees.view_sensitive

  Parameters: company_id* action* ids from to leave_type_id * = required

• buddy_punching_review Changes data

  HR's review of buddy punching (docs/attendance-security.md §19). Signals are evidence, never a verdict, and change no attendance. attendance.buddy.view: action people (scores with what was found, highest first), signals (filters employee, kind, status), presence (filters employee, status, failed). attendance.buddy.review: action decide_signal (id, decision confirm|dismiss, note; dismissing takes its weight off the score), review_presence (id, decision excuse|confirm, note). attendance.buddy.export: action export (the people table as rows). Same API: buddy-punching/*.

  Needs: attendance.buddy.export attendance.buddy.review attendance.buddy.view

  Parameters: company_id* action* id decision note employee kind status failed * = required

• buddy_punching_settings Changes data

  The four layers against one employee clocking in for another (attendance.buddy.manage, docs/attendance-security.md §19). action get: each layer's mode, settings, rules, and whether the face model is on the server. action set with layer bp_face|bp_device_key|bp_presence|bp_pattern: inherit (use the Mihnaro default), or mode off|flag|refuse (bp_pattern can only flag); bp_face: enrol_required (the biometric photo in the app before anything else), enrol_approval (HR approves it before it counts), enrol_remind_days, enrol_photo_days, blink_required (a blink on a short clip as well as the head movement), weak_action flag|refuse, refused_action allow|flag|refuse; bp_presence: per_shift 1–4, respond_minutes 2–60, percent 1–100; bp_pattern: tandem_seconds, tandem_min, stay_minutes, dual_minutes, window_days, notify_score; rules [{target_type all|branch|department|section|work_location|group|employee, target_id, effect include|exclude}], no include = everyone. Off by default; demo and reviewer accounts are never reached. Same API: GET settings/buddy-punching, PATCH settings/buddy-punching/{layer}.

  Needs: attendance.buddy.manage

  Parameters: company_id* action* layer inherit mode weak_action refused_action enrol_required enrol_approval enrol_remind_days enrol_photo_days blink_required per_shift respond_minutes percent tandem_seconds tandem_min stay_minutes dual_minutes window_days notify_score rules * = required

• clock Changes data

  Clock in or out now, under the company's clocking rules (network, work location with lat and lng, days off, QR only). action: in or out, or scan with a work location's QR code (qr_token, and t and s of a rotating code: the parts of its /clock/qr/{token}?t=&s= link); attendance_function_id for a function (break, visit...). Punches are always now: a past time (occurred_at) is refused, since only the mobile app keeps punches offline and proves their time.

  Needs: self.clock

  Parameters: company_id* action* qr_token t s lat lng attendance_function_id occurred_at * = required

• clocking_devices Changes data

  The phones and browsers employees clock from (attendance.security.review, docs/attendance-security.md). action list (filters employee_id, kind phone|browser, status pending|approved|blocked|retired, device), or for one device (id): approve, block, reset (the next punch from it needs approval again), rename (label), share (shared true/false: a shared computer, exempt from the same-device check; browsers only). action reset_employee with employee_id resets all of an employee's phones.

  Needs: attendance.security.review

  Parameters: company_id* action* id employee_id kind status device label shared * = required

• delete_time_setup_item Changes data

  Delete a time setup item by kind and id (attendance_setup.manage). A shift or work location still in use is kept, with an error.

  Needs: attendance_setup.manage

  Parameters: company_id* kind* id* * = required

• employee_clocking_from Changes data

  Where one employee clocks from (attendance.clocking_from.manage, docs/branch-settings.md §2.8). action get: their own choice, the branch's and what applies. action set with clocking_from: both, web, mobile or device (the fingerprint or face device only; refused while no working device serves their branch), or follow to go back to the branch's.

  Needs: attendance.clocking_from.manage

  Parameters: company_id* employee_id* action* clocking_from * = required

• face_templates Changes data

  Face templates (attendance.face.manage, docs/attendance-security.md §19). A template is encrypted numbers, and neither it nor any picture is ever returned, including the photo waiting for approval, which HR sees on the screen or the API only. action missing: who hasn't taken the biometric photo their company asks for. action list (filters employee, review pending|approved): status, similarity to the profile photo, enrolled and last matched. action consents (filter employee): the audit trail of consent and template events. action approve (id, note): HR accepts an enrolment. action reset (employee_id, note): deletes the template, and the next selfie enrols again. Same API: buddy-punching/faces, buddy-punching/consents.

  Needs: attendance.face.manage

  Parameters: company_id* action* id employee_id employee review note * = required

• get_clock_button_scope Reads only

  "Hide the clock button outside the work location" (attendance_setup.manage, docs/attendance-security.md §17): whether the mobile app shows the clock in/out button only inside a work location, and for whom: scope all, or chosen branch_ids, department_ids and employee_ids (any of them reaches the employee). branch_id reads a branch's own value (empty: the company's). choices lists what that level may name: a branch's own value only that branch, its departments and its employees.

  Needs: attendance_setup.manage

  Parameters: company_id* branch_id * = required

• get_clocking_security Reads only

  Clocking security settings (attendance.security.manage, docs/attendance-security.md): each anti-spoofing check's mode (off, flag, hold, block), the numbers they use, whether Play Integrity, App Attest and a GeoIP database are configured on the server, the office Wi-Fi networks, and the clocking rules set elsewhere in Attendance setup (allowed IPs, office network, selfie, rotating QR). branch_id reads a branch's own values.

  Needs: attendance.security.manage

  Parameters: company_id* branch_id * = required

• get_my_attendance Reads only

  Your attendance for a month (YYYY-MM, this month by default): each day with its status (present, late, absent, leave, holiday, weekend), worked minutes and records, plus today's records and whether you are clocked in, and clock: today's shift, state (not_in, in, out), since, whether clocking in is closed and why, and what clocking needs (location_required, qr, qr_only, photo_required).

  Needs: self.attendance.view

  Parameters: company_id* month * = required

• get_my_schedule Reads only

  Your work schedule from from to to (YYYY-MM-DD, up to 62 days; the next 7 days by default): each day with working_day, weekend, holiday (its name), day_off (a day off given in the schedule), assigned (from the published schedule rather than your own shift), shift {name, type, start, end, color} and an approved leave {type, hours}.

  Needs: self.schedule

  Parameters: company_id* from to * = required

• get_my_timesheet Reads only

  Your timesheet period holding week (any date in it; today by default) with its entries, and all your periods with their timesheet ID, hours, contribution percentage and status.

  Needs: self.timesheets.view

  Parameters: company_id* week * = required

• get_team_attendance_today Reads only

  One day of the team's attendance (attendance.view, today by default): counts of present, late, absent, not yet, on leave and off, and each person in reach with their status and first and last punch.

  Needs: attendance.view

  Parameters: company_id* date * = required

• get_team_calendar Reads only

  The team calendar for a month (YYYY-MM, this month by default): leaves — who is off or working remotely (remote), with start, end and hours for an hour leave, among the people the branch's "Who's off shows" setting picks; the leave type only for someone with leaves.view — plus holidays {date: name} and the company events.

  Needs: leaves.view self.team_calendar

  Parameters: company_id* month * = required

• get_time_settings Reads only

  Attendance setup (clocking rules and missing punches) or Timesheets setup: section attendance or timesheets. Needs attendance_setup.manage.

  Needs: attendance_setup.manage

  Parameters: company_id* section* * = required

• list_attendance_recommendations Reads only

  Attendance recommendations (absence, lateness, early leaving, incomplete days, overtime) for the employees your role reaches (attendance.recommendations.view; attendance.view or attendance.manage grant it): status pending (default), applied or ignored, kind, from, to. 50 a page.

  Needs: attendance.manage attendance.view

  Parameters: company_id* status kind from to page * = required

• list_attendance_records Reads only

  Attendance records of the employees your role reaches (attendance.view), 50 a page: from and to (YYYY-MM-DD, this month by default), employee_id, shift_id (work shift: people on it), state (incomplete, complete, trusted).

  Needs: attendance.view

  Parameters: company_id* from to employee_id shift_id state page * = required

• list_attendance_sheets Reads only

  ZenHR's Attendance Sheets (attendance.manage): sheets imported from attendance machines, newest first, 50 a page, each with the dates it covers, punches read (success), failures (no employee + unreadable rows) and status (completed, with_errors, failed). Filters: machine_id, status, from and to (import date, YYYY-MM-DD). template_machine_id instead returns that machine's blank sheet (rows of cells, headings first) in its template's columns. Import a sheet with the API (POST biometric-devices/{id}/sheet).

  Needs: attendance.manage

  Parameters: company_id* machine_id status from to template_machine_id page * = required

• list_machine_users Reads only

  A biometric machine's users (attendance_setup.manage, docs/attendance.md): each number (pin) the machine reported or sent punches for, its name and card on the machine, how many punches and the last one, and the employee it links to (null when none). Attendance sheets exported from the machine are read with POST biometric-devices/{id}/sheet in the API.

  Needs: attendance_setup.manage

  Parameters: company_id* device_id* * = required

• list_missing_punches Reads only

  Missing-punch requests of the employees your role reaches (attendance.missing_punches.view; attendance.view or attendance.manage grant it), newest first, 50 a page: status (pending, approved, rejected, cancelled, withdrawn), from and to (punch date, YYYY-MM-DD), employee_id, employee_status. Decide them with the request tools.

  Needs: attendance.manage attendance.view

  Parameters: company_id* status from to employee_id employee_status page * = required

• list_punch_log Reads only

  The punch log (attendance.security.review, docs/attendance-security.md): self-service punches of the employees your role reaches with their context (channel, IP, browser or phone, location and accuracy, mock flag, Wi-Fi, offline proof, integrity verdict) and what the security checks found, newest first, 50 a page. Filters: employee_id, branch_id, from and to (YYYY-MM-DD), channel (web, mobile, mcp), device (device id), ip, flagged (only punches with findings), status (accepted, flagged, held, blocked), review (pending, approved, rejected). id returns one punch.

  Needs: attendance.security.review

  Parameters: company_id* id employee_id branch_id from to channel device ip flagged status review page * = required

• list_time_setup Reads only

  The company's time setup by kind: shifts (work shifts, with how many employees work each), overtime_types, holidays (of year, this year by default), geolocations (work locations), biometric_devices (attendance machines; tokens are never listed) or detected_devices (clocks that called in from the caller's own public IP and are not added yet: serial, family, model, last call; add one with save_time_setup_item kind biometric_devices). Needs attendance_setup.manage.

  Needs: attendance_setup.manage

  Parameters: company_id* kind* year * = required

• list_zenhr_history Reads only

  History imported from ZenHR (docs/zenhr-import.md), 50 a page, for the employees your role reaches. kind days: ZenHR's day analysis (status, shift, first in/last out with place, minutes required, worked, late, early out, overtime, variance; attendance.manage). kind punches: every punch (function, who added it, machine, card id, place; attendance.manage). kind balances: vacation balances per year (previous, opening, taken, adjustments, encashed, available, financial effect; leaves.manage). Filters: employee_id, from, to (YYYY-MM-DD), status present|absent|partial (days), leave_type_id and year (balances).

  Needs: attendance.manage attendance.view leaves.manage

  Parameters: company_id* kind* employee_id from to status leave_type_id year page * = required

• live_location Changes data

  Mandatory live location for field staff (docs/live-location.md). live_location.manage: action get_policy; action set_policy (fields: enabled, mode while_clocked_in|during_shift|always_when_app_open, interval_seconds, distance_meters, max_silence_minutes, retention_days, reason {en, ar}, rules [{target_type all|branch|department|section|work_location|group|employee, target_id, effect include|exclude}] replacing the current ones; an employee rule is their override). live_location.view (your role's scope, the branch you work in): action positions (filters: branch, department, group, status online|lost|offline|none, q) = latest position, age, battery, accuracy, mocked flag and status per employee; action trail (employee_id, date) = that day's points. action export: the export's rows (with employee_id and date a trail, else the positions by filters), logged as an export. Every positions and trail call is recorded in the location view log. app_policy.manage: action get_rule / set_rule with policy app_lock (fields: enabled, when every_open|after_background, after_minutes, methods biometric|biometric_or_passcode, rules) or punch_auth (fields: enabled, methods, rules): the same targeting; punches then need local_auth {method face|fingerprint|passcode, at}; or screen_capture (fields: enabled): the whole app kept out of screenshots and recordings, company-wide, on by default (Field-proof screens always are); or phone_sharing, one account per phone (fields: inherit = use the Mihnaro default, mode allow|warn|block, max_accounts 1–10, rules; no include rule = everyone; docs/platform-control.md «الهاتف المشترك»); or event_location, keeping the phone's GPS point with app sign-ins and opens (fields: inherit = use the Mihnaro default auto|on|off, enabled, rules; no include rule = everyone; only from people who already allowed location on the phone; never demo or reviewer accounts; docs/platform-control.md «موقع الأحداث»); or location_required, location as a condition of using the app (fields: inherit, enabled, precise, reason_en, reason_ar, rules; the app gates until location is on and the server refuses with location_required; never demo or reviewer accounts; docs/platform-control.md «الموقع شرط لفتح التطبيق»); or context_device|context_network|context_battery|context_permissions|context_security|context_time|context_locale|context_health, each category of phone details the app sends with opens, sign-ins and punches (fields: inherit, enabled, retention_days 7–730, rules; docs/platform-control.md «بيانات الهاتف»).

  Needs: app_policy.manage live_location.manage live_location.view

  Parameters: company_id* action* fields filters employee_id policy date * = required

• log_timesheet Changes data

  Your timesheet: action add (project_id, work_date, hours, description), delete (entry_id; a draft or returned entry) or submit (week: a date in the period).

  Needs: self.timesheets.log

  Parameters: company_id* action* project_id work_date hours description entry_id week * = required

• my_face_consent Changes data

  The employee's own face consent and presence check (self.face, docs/attendance-security.md §19). action get: the consent text, your answer, whether a template exists, and an open presence check. action withdraw: withdraws consent and deletes the template at once. Giving consent and taking the selfie only happen in the mobile app.

  Needs: self.face

  Parameters: company_id* action* * = required

• phone_biometric_keys Changes data

  Phone keys bound to the faces and fingers on the phone (docs/attendance-security.md §19). action list (attendance.buddy.view; filters employee, status active|broken|awaiting_key|retired). action approve or reset (attendance.device_key.approve; id): after a new face or finger a key is "broken" and that phone follows the company's setting until HR approves it, then the app makes a new key; reset takes a key away for a lost or changed phone. Same API: buddy-punching/keys.

  Needs: attendance.buddy.view attendance.device_key.approve

  Parameters: company_id* action* id employee status * = required

• review_punch Changes data

  Decides a suspicious or held punch of the punch log (attendance.security.review, docs/attendance-security.md): decision approve or reject, note, approve_device (also approve its pending phone or browser). Approving a held punch applies it exactly like a normal punch at its original time, for that employee only; rejecting writes nothing. A flagged punch is already in attendance: the decision only records the review.

  Needs: attendance.security.review

  Parameters: company_id* id* decision* note approve_device * = required

• review_timesheets Changes data

  Timesheets submitted by the employees your role reaches (timesheets.approve): with no decision, lists the submitted periods (timesheet ID, hours, contribution percentage, entries); with employee_id, week and decision (approved or rejected), approves or returns that period.

  Needs: timesheets.approve

  Parameters: company_id* employee_id week decision * = required

• save_attendance_record Changes data

  Record a day for an employee your role reaches (attendance.records.manage): work_date, clock_in and clock_out (HH:MM). With replace true the day's records are replaced (correct a day, e.g. a forgotten clock-out). Or trust (or untrust) a record with record_id.

  Needs: employees.view_sensitive

  Parameters: company_id* employee_id work_date clock_in clock_out replace record_id * = required

• save_clock_button_scope Changes data

  Changes "Hide the clock button outside the work location" (attendance_setup.manage, docs/attendance-security.md §17); send only what changes. clock_hide_outside_location (off by default), scope: all or chosen, branch_ids, department_ids, employee_ids (lists replace the saved ones). branch_id saves a branch's own value, which can name only that branch, its departments and its employees; without it, the company's value, which only someone working across every branch may change. Only hides the button in the app: the punch check is "Clock-in must be at a work location" (clock_geofence).

  Needs: attendance_setup.manage

  Parameters: company_id* branch_id clock_hide_outside_location scope branch_ids department_ids employee_ids * = required

• save_clocking_security Changes data

  Changes clocking security (attendance.security.manage, docs/attendance-security.md); send only what changes. checks: {check: off|flag|hold|block|on} for mock_location, integrity, new_device, browser_binding, shared_phone, shared_browser, offline_unproven, accuracy, ip_location, travel, wifi ("on" = the usual action: hold for offline_unproven, new_device and browser_binding, flag otherwise; integrity can only flag until a provider is configured). clock_sec_shared_window_hours, clock_sec_desktop_accuracy_m, clock_sec_travel_kmh, clock_sec_ip_distance_m, clock_sec_geoip_distance_km (IP city vs GPS, km), clock_sec_office_ips, clock_sec_datacenter_ips (comma-separated IPs or CIDR ranges), clock_sec_alert_email. clock_offline_enabled (the mobile app keeps punches made with no internet and sends them later) and clock_offline_hours (1–168, how far back). branch_id saves a branch's own values. add_wifi {bssid, ssid, label, branch_id, work_location_id} adds an office Wi-Fi access point; remove_wifi_id removes one.

  Needs: attendance.security.manage

  Parameters: company_id* branch_id checks clock_sec_shared_window_hours clock_sec_desktop_accuracy_m clock_sec_travel_kmh clock_sec_ip_distance_m clock_sec_geoip_distance_km clock_sec_office_ips clock_sec_datacenter_ips clock_sec_alert_email clock_offline_enabled clock_offline_hours add_wifi remove_wifi_id * = required

• save_time_settings Changes data

  Change attendance setup or timesheets setup (section), sending only the settings that change in values, e.g. {"clock_geofence": true, "mp_max_days": 30} or {"ts_period": "biweekly"}. get_time_settings lists them. Punches by shift (docs/attendance.md): punch_in_window_minutes (early clock-in window before a shift, default 60), punch_out_grace_minutes (clock-out grace after it, past midnight too, default 30), shift_punches_from (Y-m-d H:i on the company clock: punches from then follow the shift; earlier ones keep the calendar day; empty = all, "off" = never).

  Needs: attendance_setup.manage

  Parameters: company_id* section* values* * = required

• save_time_setup_item Changes data

  Add or change a time setup item (attendance_setup.manage). kind shifts or overtime_types: the whole item in fields, as on the screen (a shift: name {en, ar}, type, start_time, end_time..., punch_in_window_minutes and punch_out_grace_minutes for punches by shift, empty = the device's then the company's; an overtime type: name, applies_on, rate, allowance_method...). kind holidays: name, date, end_date, religions, recurring. kind geolocations: name, latitude, longitude, radius_m, restricted. kind biometric_devices: name, serial, work_location_id, punches_from (Y-m-d: older punches are kept but not added to attendance); a new machine's token is shown once. Give id to change one; for holidays, geolocations and machines send only what changes.

  Needs: attendance_setup.manage

  Parameters: company_id* kind* id fields* * = required

• schedule_employees Changes data

  The employee shift schedule and work locations, for the employees your role reaches. action list, week and regular need attendance.shift_planner.view; assign_shift, plan and publish attendance.shift_planner.manage; set_locations and replace_location attendance.manage; location_for_everyone attendance_setup.manage (attendance.manage grants them all). action list: schedule rows between from and to (a week by default). action assign_shift: employees, shift_id (or "off"), start_date, end_date (none = open-ended), conflict replace or keep. action plan (ZenHR's roster): shift_ids, start_date, end_date (up to two months, e.g. a month), optional employees, max_in_a_row, days_off_a_week, max_weekly_hours, fair_nights: drafts days. action publish: start_date, end_date, optional employees, notify: publishes the drafts. action week: the Employee Shifts week (week = any date in it; filters q, department, job_role, manager, gender, schedule with|without) as one row per employee with a cell per day (the CSV export). action regular: regular (non-roster) shift assignments and each person's own default shift. action set_locations: employees, locations and mode assign, unassign or replace. action replace_location: everyone at from_location moves to to_location. action location_for_everyone: location_id with mode assign, unassign or replace for every active employee in reach. action reprocess_punches (attendance_setup.manage): match machine punches to employees again.

  Needs: attendance.manage attendance_setup.manage

  Parameters: company_id* action* from to employee employees shift_id start_date end_date conflict shift_ids max_in_a_row days_off_a_week max_weekly_hours fair_nights notify week q department job_role manager gender schedule from_location to_location location_id locations mode * = required

• shift_setup Changes data

  Shift and overtime setup actions (attendance_setup.manage, docs/attendance.md). action get: shift_id with its fields and employee count. action copy_to_roster: a roster copy of shift_id. action sync: give shift_id to every active employee who has no shift (not roster or archived shifts). action get_overtime_limit / set_overtime_limit: the Limit Setup, ot_limit_scope per_type|total, ot_total_limit_hours (0-744), ot_total_limit_period day|week|month.

  Needs: attendance_setup.manage

  Parameters: company_id* action* shift_id ot_limit_scope ot_total_limit_hours ot_total_limit_period * = required

• team_schedule Changes data

  Work shifts HR shares with managers (docs/attendance.md «مشاركة جداول الدوام»). HR (attendance_setup.manage): action shares (shift_id) lists who a shift is shared with; action share (shift_id, targets [{target_type department|group|employee, target_id, can_edit}]) replaces them. Managers (shifts.assign_team) and HR: action list: the shifts shared with you (every shift for HR) and your team; action assign: employees (your team only), shift_id (a shared shift, or "off"), start_date, end_date (none = open-ended; the same date for one roster day), conflict replace|keep, draft; action clear: employees, start_date, end_date; action plan: the shift planner for your team (shift_ids shared with you, start_date, end_date at most 62 days, employees optional = whole team, max_in_a_row, days_off_a_week, max_weekly_hours, fair_nights), drafts only; action copy: source_from, source_to, target_from, target_to (same length or a multiple), employees optional, draft; days on shifts not shared with you are not copied; action publish: start_date, end_date, employees optional (a manager publishes drafts on shared shifts and days off only); action update_shift: shift_id and the shift fields, only where a share lets you change it.

  Needs: attendance_setup.manage shifts.assign_team

  Parameters: company_id* action* shift_id targets employees start_date end_date conflict draft shift_ids source_from source_to target_from target_to max_in_a_row days_off_a_week max_weekly_hours fair_nights * = required

Balances, asking for time off, the team's leaves and decisions on them, adjustments and leave types.

Try asking: «Show my remaining annual leave» «Who is on leave next week?»

• decide_leave Changes data

  Decide the step a pending leave request waits on, when it is waiting on you (its approval chain: the employee's manager, HR with requests.manage, or the people an approval template names): leave_id, decision approved or rejected, decision_note (some types need it to reject), non_deduct (approve without taking the days; needs leaves.manage and a type that allows it). Not your own.

  Needs: leaves.manage requests.manage self.approvals.decide

  Parameters: company_id* leave_id* decision* decision_note non_deduct * = required

• get_my_leaves Reads only

  Your leave balances for a year (this year by default) and your leave requests with their status.

  Needs: self.leaves.view

  Parameters: company_id* year * = required

• list_leave_adjustments Reads only

  Leave balance adjustments (kind=adjustments, default) or balances moved into a new year (kind=moved) for the employees your role reaches (leaves.adjustments.view, or leaves.moved_balances.view for kind=moved; leaves.view or leaves.manage grant both), 50 a page: leave_type_id, year, employee_id. Add or remove them with manage_leave_balances.

  Needs: leaves.manage leaves.view

  Parameters: company_id* kind leave_type_id year employee_id page * = required

• list_leave_types Reads only

  Time off types (leave_setup.manage), of one category (annual, casual, hourly for leaves by the hour, sick) or all, with every setting and how many employees have each.

  Needs: leave_setup.manage

  Parameters: company_id* category * = required

• list_team_leaves Reads only

  Leave requests of the employees your role reaches (leaves.view): status pending (default), approved, rejected, withdrawn or all; kind days or hours (leaves by the day or by the hour); leave_type_id, employee_id, from, to. 50 a page.

  Needs: leaves.view

  Parameters: company_id* kind status leave_type_id employee_id from to page * = required

• manage_leave_balances Changes data

  Leave balances of the employees your role reaches. action balances (leaves.view): employee_id, year or as_of. Each action needs its own permission, and leaves.manage grants them all: add_leave (leaves.manage) (approved leave for an employee: employee_id, leave_type_id, start_date, end_date or start_time and end_time, reason), adjust (leaves.adjustments.manage: employee_id, leave_type_id, year, days (+/-), reason), delete_adjustment (adjustment_id; leaves.adjustments.manage, or leaves.moved_balances.manage for a moved balance), move (leaves.moved_balances.manage: leave_type_id, year, max_days; the whole company), set_setup (leaves.balance_corrections.manage: (employee_id, leave_type_id, entitlement_days, open_balance, carry_balance, balance_year, active; reset true for the company setup), apply_type (leaves.balance_corrections.manage: leave_type_id to employee_ids or everyone, with entitlement_days and open_balance), encashments (leaves.encashments.view: year, default this year; the encashments of the employees in scope), encash (leaves.encashments.manage: employee_id, leave_type_id, days, notes), cancel_encashment (leaves.encashments.manage: encashment_id). action balance_breakdown (leaves.view; employee_id, leave_type_id): ZenHR's Show balance, each year split into opening, previous, adjustments, encashed, hourly, total, used, pending, remaining.

  Needs: leaves.manage leaves.view

  Parameters: company_id* to_leave_type_id action* employee_id employee_ids leave_type_id year as_of days reason max_days start_date end_date start_time end_time entitlement_days open_balance carry_balance balance_year active reset notes adjustment_id encashment_id * = required

• request_leave Changes data

  Ask for time off (action request): leave_type_id, start_date and end_date (YYYY-MM-DD), or for an hourly type start_date with start_time and end_time (HH:MM); reason, half_day. A type that needs a document is asked for on the screen or the API. Or withdraw your pending request (action withdraw, leave_id).

  Needs: self.leaves.cancel self.leaves.request

  Parameters: company_id* action* leave_type_id start_date end_date start_time end_time reason half_day leave_id * = required

• save_leave_type Changes data

  Add a time off type (category annual, casual, hourly or sick) or change one with leave_type_id (leave_setup.manage), sending its whole form in fields as the screen does: name {en, ar}, entitlement_days (entitlement_hours for hourly), balance_type, notice and weekend rules, exceeding, accumulation, balance_setups, encashment, rules [{type, values}], hourly limits and deductions, sick_slices, switches (true/false). With balance_update_type "new" and effective_date, a changed amount counts from that date. delete true deletes an unused type.

  Needs: leave_setup.manage

  Parameters: company_id* category leave_type_id fields delete * = required

Filing any kind of request, what waits for your approval, deciding it, following its steps, comments and delegation.

Try asking: «What is waiting for my approval?» «Where is my expense request?»

• cancel_request Changes data

  Cancel an approved request or time off (ZenHR's Request to Cancel). action cancel: HR over the employee (requests.manage, or leaves.manage for time off) cancels it now; the employee's own ask walks the cancellation cycle (the request's approval chain, step by step); reason optional. Its payroll transactions, in-advance salary, hour deductions and probation extension are taken back, unless a closed payroll month already paid them. action decide: the approver of the step it waits on (or HR over the employee, whose decision is final) approves or rejects (decision approved|rejected, note optional); the last approval cancels it. action list: asks waiting for your decision, with cancel_chain, waiting_on and cancel_decisions. kind requests|leaves, id.

  Needs: leaves.manage requests.manage self.leaves.cancel self.requests.cancel

  Parameters: company_id* action* kind id reason decision note * = required

• decide_request Changes data

  Act on requests from the approvals page. action decide: approve or reject the step items wait on, when it is waiting on you (items: "request:ID" or "leave:ID", several at once; ones you can't decide are skipped). action override: decide one item waiting on someone else, when you may override it (the approval template's admins, else HR or a manager above). action withdraw: pull back your own pending request (items: one "request:ID"). decision approved or rejected, decision_note. Never your own request.

  Needs: leaves.manage requests.manage self.approvals.decide

  Parameters: company_id* action* items* decision decision_note * = required

• file_request Changes data

  File a request of a type (see list_request_types) with its fields: for yourself, or with employee_id for someone you may file for (requests.manage in scope, or their manager when the type allows it). It goes through the type's approval chain; a type with no approval needed is approved at once. Attachments are sent through the API or the screen.

  Needs: requests.manage self.requests.file

  Parameters: company_id* type* fields* employee_id * = required

• get_approval_cycle Reads only

  A request's approval cycle, as ZenHR shows it (docs/approvals.md): every step in order with approver (name), approver_ids, step and step_label, status (approved, rejected, skipped, delegated, pending, waiting = ZenHR's "Waiting / Draft", withdrawn), received_at, decided_at, note, override, on_behalf_of, imported (ZenHR history). kind requests (an employee request: financial transaction, overtime, loan, miscellaneous, missing punch…) or leaves (time off), id. Whoever may see the request: the employee, HR over them, or an approver.

  Needs: leaves.manage leaves.view requests.manage requests.view self.approvals.decide self.leaves.view self.requests.view

  Parameters: company_id* kind* id* * = required

• list_approvals Changes data

  The approvals page, leave and employee requests together: tab approvals (waiting on me, or what I decided: status pending, approved, rejected, all), my (my own requests), team (the people below me or in my requests.view scope) or override (pending ones I may decide for their approver); type filters by request type key or "leave"; employee_id one employee; sort employee, serial, requested (default, newest first), received or my_action, with dir asc or desc. Serial numbers are as ZenHR shows them ("LEAV - 1000000631950"), list_label the request type name ZenHR shows. Each row has item ("leave:ID" or "request:ID"), who it is from, what it waits on, can_act and can_override. my_action filters by what I did: waiting (not reached me yet), pending, approved, rejected, withdrawn, approved_non_deduct, added_by_hr, delegated, skipped (my step was skipped), cancelled, cancel_requested, none. On tab approvals with status pending, approved requests whose cancellation waits on my step are listed too (action_type cancellation, can_decide_cancel; decide them with cancel_request action decide); action_type approval|cancellation keeps one cycle (ZenHR's "Action type"). On tab my or team with a type that has its own columns (leave, transaction, overtime, loan, general, business_trip, missing_punch, timesheet, vacation_encashment), each row has that type's columns and filters narrows them: {key: value} for a select or yes/no (yes|no), {key_from, key_to} (YYYY-MM-DD) for a date; the answer lists the columns and filters. With request_id, one request with its details and decisions.

  Needs: requests.manage requests.view self.approvals.decide self.leaves.view self.requests.view

  Parameters: company_id* tab status type request_id my_action action_type filters employee_id sort dir * = required

• list_request_types Changes data

  The request types the company offers (expense, overtime, missing punch, general, vacation resumption, vacation encashment, HR letter…): key, label, whether employees file it themselves or only for someone else, whether it takes an attachment, its default approval chain, the fields it asks for and the choices of fields that take one (options: field → value and label).

  Needs: requests.manage self.requests.file

  Parameters: company_id* * = required

• manage_approval_delegation Changes data

  Approval delegation (ZenHR "Delegated"): list the delegations you gave or received, delegate your approval steps to a colleague (delegate_id is their user id; starts_on, ends_on empty = until ended, note), or end one of yours (delete, id). The delegate decides on your behalf and each decision says so.

  Needs: requests.manage self.approvals.delegate

  Parameters: company_id* action delegate_id starts_on ends_on note id * = required

• manage_approval_setup Changes data

  Approval setup (approval_setup.manage). action get: each request kind's chain (empty = its default) and the approval templates. action save_chains: chains {kind: value}, value one of manager, hr, "manager,hr", "tpl:<template id>" (or "none" for payroll_batch). action save_template: add one, or change it with template_id: name {en, ar}, object_type (a transaction type such as leave, overtime, general, expense) and object_id (its sub-type), assign {work_location_ids, department_ids, section_ids, business_unit_ids, division_ids, segment_ids, hierarchy_group_ids, job_role_ids, project_ids, employee_ids}, steps in order — ZenHR's "Approved By": approvals_officer, manager, manager_2, manager_3, financial_officer, supervisor, hr, payroll, "employee:<employee id>", "department:<department or section id>", "position:<job role id>", "role:<role id>", "user:<user id>", or {kind: committee, members: ["e<employee id>" or user ids]}; action approvers lists every one this template (template_id) or a new one may name, from its own branch only, skip_after with skip_after_unit days|hours, notify_user_ids, override_enabled with overrider_ids and override_self. action delete_template: one no chain points at.

  Needs: approval_setup.manage

  Parameters: company_id* action* chains template_id fields * = required

• manage_miscellaneous_requests Changes data

  ZenHR's "Manage Miscellaneous Requests". action list (default): the miscellaneous (general) requests of the employees in your requests.miscellaneous.view scope (or requests.view / requests.manage), filtered by miscellaneous_type_id, status (pending, approved, rejected, cancelled), employee_id, active (active (default), inactive, all), from/to (effective date) and q; each row has the serial number, employment number, employee, transaction name, effective date, status and whether the employee is active. action update (requests.miscellaneous.manage or requests.manage, request_id): change miscellaneous_type_id, subject, effective_date, end_date, details or fields {field id: value}. action delete (requests.miscellaneous.manage or requests.manage, request_id): delete the request and its trail.

  Needs: requests.manage requests.view

  Parameters: company_id* action request_id miscellaneous_type_id status employee_id active from to q page per_page end_date subject effective_date details fields * = required

• request_comments Changes data

  The comments under a request's Approval Cycle, as in ZenHR ("Comments and replies are visible to anyone who has access to this item", docs/approvals.md). kind requests (an employee request) or leaves (time off), id. action list (default): the comments oldest first, each with id, author, body and at. action add: post body (up to 2000 characters). Whoever may see the request: the employee, HR over them, their managers, or an approver.

  Needs: leaves.manage leaves.view requests.manage requests.view self.approvals.decide self.leaves.view self.requests.view

  Parameters: company_id* kind* id* action body * = required

Your payslips, payroll runs and their approval, loans and transactions, salary scales, insurance, travel, end of service and payroll setup.

Try asking: «Summarize this month's payroll» «Show my last payslip»

• download_payslip_pdf Changes data

  A payslip as a PDF file, as GET /api/v1/payslips/{id}/pdf: my own once its run is approved, or any in my payroll scope. Returns filename, mime, size and the file as base64, plus the download link in the app. lang en or ar (default: my language).

  Needs: self.payslips.download

  Parameters: company_id* payslip_id* lang * = required

• download_salaries_excel Reads only

  The Salaries report as ZenHR's Excel sheet (docs/payroll-salaries-excel.md), as GET /reports/salaries/run?format=xlsx_colored (colored true, the default) or format=xlsx (colored false, "Not colored"): ZenHR's layout read from its own file: logo, title, branch and date, a band row (General Details, Incomes, Reserved Transactions, Company Expenses, Deductions, Company Contributions) over the columns in ZenHR's order, a Serial column, cells filled in their band's colour (or all white), money as "[$IQD] #,##0.000" and a Totals row; right to left in Arabic. filters: the Salaries report filters as run_report takes them (years[], months[], employees[], settlement_type, cols, show…). saved_id starts from saved options. lang en or ar (default: my language). Returns filename, mime, size and the file as base64.

  Needs: employees.view_sensitive

  Parameters: company_id* filters saved_id lang colored * = required

• earned_wage Changes data

  Earned wage access, the same as the screens. action available: what I can take now in the open payroll month (earned so far, taken, limit, available, requests left, fee, and why not when blocked). To ask, file the "earned_wage" request type (amount, reason) with the requests tools. action settings: the company settings; action update_settings (payroll_setup.manage): any of ewa_enabled, ewa_percent (1-100 of what is earned), ewa_max_requests (a month), ewa_min_amount, ewa_fee (deducted with the advance), ewa_last_day (0 = any day), ewa_include_allowances, ewa_min_service_days.

  Needs: payroll_setup.manage self.earned_wage

  Parameters: company_id* action* ewa_enabled ewa_percent ewa_max_requests ewa_min_amount ewa_fee ewa_last_day ewa_include_allowances ewa_min_service_days * = required

• list_air_ticket_policies Reads only

  Air ticket policies (payroll_setup.manage, HR module). Without policy_id: every policy with its tickets per period, period_months, period_anchor hire|calendar, accrual period_start|monthly, amount per ticket, family_members covered, eligible_after_months, applies_to all|assigned, expiry, cash_out, switches and employees_count. With policy_id: that policy plus the employees in my payroll.manage scope it was given to, with their opening_balance.

  Needs: payroll.manage payroll_setup.manage

  Parameters: company_id* policy_id * = required

• list_air_tickets Reads only

  Air tickets of the employees in my payroll scope (payroll.view or payroll.manage, HR module). kind transactions: tickets used, newest travel first, with owners, tickets, amount, cash_out, destination, dates, payment_status paid|unpaid and deletable; filters employee_id, policy, status paid|unpaid, payment cash_out|booked, payroll in_payroll|off_cycle, request_status (a request status or added_by_hr), from, to (travel date), paid_from, paid_to. kind balances: each active employee under each of their policies: total, used, pending, balance, amount, per_period, eligible_from, current period; filter policy. page and per_page (10-200).

  Needs: payroll.manage payroll.view

  Parameters: company_id* kind* employee_id policy status payment payroll request_status from to paid_from paid_to page per_page * = required

• list_business_travel Reads only

  Business travel setup (payroll_setup.manage, HR module). kind setup: trip_per_diem_type_id, trip_payment in_payroll|off_cycle, trip_air_ticket_type_id, trip_accommodation_type_id, trip_remind_days, trip_expense_type_ids, trip_slip_breakdown, trip_show_amounts and the per diem components (id, name). kind policies: travel policies with position_ids, destinations (category domestic|international, country and cities or countries, travel_types, air_classes, limits, hotel_tiers, components {type_id, amount, mandatory}) and switches. kind policy: one policy (policy_id).

  Needs: payroll_setup.manage

  Parameters: company_id* kind* policy_id * = required

• list_eos_policies Reads only

  End-of-service (STB) policies (HR module, payroll_setup.manage): termination category, default flag, minimum years, tiers (from_years, to_years, days_per_year), worth tiers (percent), contract type, excluded unpaid leave, nationalities, allowances counted, calculation options and salary caps. policy_id returns one policy; otherwise filters name, category, contract_type limited|unlimited, defaults_only.

  Needs: payroll_setup.manage

  Parameters: company_id* policy_id name category contract_type defaults_only * = required

• list_insurance Reads only

  Medical insurance policies (HR module, payroll.view or payroll.manage): insurer, policy number, dates, adult and minor cost and currency, pro rata, per employee, branch, and the members whose employee is in my scope (owner: the employee or a family member, dependents, custom cost, monthly deduction, cost). policy_id returns one policy; active true keeps the policies in force today.

  Needs: payroll.manage payroll.view

  Parameters: company_id* policy_id active * = required

• list_my_payslips Changes data

  My payslips from approved payroll runs, newest first, with their lines and slip_type (payroll, in_payroll_settlement or off_cycle_settlement) and slip_title. With payslip_id, one payslip: my own once approved, or any in my payroll scope.

  Needs: self.payslips.view

  Parameters: company_id* payslip_id * = required

• list_payroll Changes data

  Payroll data for payroll staff (payroll.view or payroll.manage), for the employees in scope. kind runs: payroll runs (filters month, kind regular|off_cycle, status draft|approved). kind run: one run with its payslips (run_id). kind payslip: one payslip (payslip_id) with its header (ZenHR slip details) and lines. kind transactions: financial transactions (month, employee_id, type earning|deduction, off_cycle, transaction_type_id, status, q). kind transaction: one transaction's details (transaction_id). kind loans: loans with what is left (employee_id, status active|settled). kind packages: an employee's salary packages (employee_id). kind templates: salary package templates. Setup lists such as transaction types, loan types, cost centers and salary bands are list_setup_form entities.

  Needs: payroll.manage payroll.view

  Parameters: company_id* kind* run_id payslip_id transaction_id transaction_type_id q employee_id month kind_filter status type off_cycle page per_page * = required

• list_payroll_costs Reads only

  Payroll costs, rates and salaries (read-only), as the API lists them. Setup kinds need payroll_setup.manage: kind exchange_rates: currency pairs by effective date with the base currency and the multi-currency switch (filters currency, branch: a branch id or "company"). kind cost_center_groups: groups with the cost centers they include (code, center). Employee kinds need payroll.view or payroll.manage and only show employees in scope: kind cost_allocations: each employee's split over cost centers for a period, status active|inactive|upcoming (employee_id, status, group). kind part_time: part-time transaction assignments (employee_id, type: a transaction type id, effective, from, to dates). kind salaries: every payslip as on Manage salaries, with who has their salary stopped (year, month 1-12, salary_type regular|off_cycle, slip_type payroll|in_payroll_settlement|off_cycle_settlement, run_status draft|pending|rejected|approved|sent, date_from / date_to YYYY-MM, in_advance yes|no, q). kind salary_batches: the Salary Batches tab, each run with its date range, headcount and net (year, month 1-12, salary_type regular|off_cycle, run_status draft|approved). kind calculate_options (payroll.manage): what Calculate offers for salary_month YYYY-MM (else the open month): the grouped picker values (branch:<id>, employee:<id>, org:<id>), the cut-off date range and the draft batches to add to. All take page and per_page; employee kinds also take the org filters department and branch.

  Needs: payroll.manage payroll.view payroll_setup.manage

  Parameters: company_id* kind* currency branch code center employee_id status group type effective from to year month salary_type slip_type run_status date_from date_to in_advance in_advance_paid q department salary_month page per_page * = required

• list_payroll_setup Reads only

  Payroll setup for payroll admins (payroll_setup.manage). kind settings: a settings section's current values (switches as booleans, id lists as arrays, the rest as strings): section payroll_setup (cut-off day, day bases, absence/unpaid calculation, gross-up, tax method, payslip options, negative balances, general finance values), in_advance (in-advance salary setup), extra_salaries (extra salaries setup), tax_setup (what comes off the taxable salary), journal (journal entries structure and account codes), provision_setup (which provisions are calculated). kind rules: a payroll rules list, section social-security, tax, extra-salaries, bank-accounts (filter branch_id), bank-templates or slip-templates.

  Needs: payroll_setup.manage

  Parameters: company_id* kind* section* branch_id * = required

• list_provisions Reads only

  Monthly provisions (vacation compensation, end-of-service benefit, extra salaries, air tickets) for the employees in my payroll scope (payroll.view or payroll.manage). kind rows: one row per employee and month with the month's provisions, adjustments and totals; filters month YYYY-MM (default this month) or from / to, stb_types (STB policy ids), contract_type limited|unlimited, employee_status active|inactive, kind_filter (employee kind). kind months: the calculated months with people, the month's provisions and the total. Provision setup is list_payroll_setup section provision_setup.

  Needs: payroll.manage payroll.view

  Parameters: company_id* kind* month from to stb_types contract_type employee_status kind_filter * = required

• list_salary_scales Reads only

  Salary scales (HR module). kind scales: the scales with structure, layers, exceed percentages, compa-ratio range, activation date and status (filter status active|inactive|draft; payroll_setup.manage). kind scale: one scale (scale_id) with its grades, bands and levels, each with min/mid/max salary, entitled_to_overtime, the ids it entitles to (job_role, loan_type, air_ticket_policy, insurance_policy, annual_leave, sick_leave) and allowances (payroll_setup.manage). kind job_grades: the job grades screen, each grade with range, ideal compa-ratio, benefits, levels, leave days, headcount, average salary, compa-ratio and who is outside the range, plus salary_scale_enforce (payroll_setup.manage). kind placement: an employee's place on the scale (employee_id, in my payroll.view or payroll.manage scope) with range and compa-ratio.

  Needs: payroll.manage payroll.view payroll_setup.manage

  Parameters: company_id* kind* scale_id employee_id status * = required

• list_stb_encashments Reads only

  End-of-service benefit encashments (HR module, payroll.stb_encashments.view, which payroll.view and payroll.manage grant; employees in my scope). kind list: encashments newest first (employee_id filter, page, per_page) with the company limits (enabled, max_percent, min_years, every_years). kind available: what an employee can take now (employee_id): service years, accrued benefit, taken before, allowed amount, eligible and the reason when not. kind settings: every encashment rule (stb_encash_* as manage_stb_encashments action settings takes them: limits, eligibility, times per years, line names, policies by contract).

  Needs: payroll.manage payroll.view

  Parameters: company_id* kind* employee_id page per_page * = required

• manage_air_ticket_policies Changes data

  Add, edit, delete and give air ticket policies (payroll_setup.manage, HR module). action create and update (policy_id): fields name_en (required), name_ar, tickets (0-20 a period), period_months (1-120), period_anchor hire|calendar, accrual period_start|monthly, amount (one ticket's value), family_members, eligible_after_months, applies_to all|assigned, expire_option none|immediately|after with expire_after_months, distribution per_person|shared, default_payroll in_payroll|off_cycle, default_request_type cash_out|ticket, transaction_type_id, gl_identifier, clearance_account, setups[] {position_ids[], nationalities "a,b", years_from, years_to, amount, currency, beneficiaries[] {relation parent|spouse|child|sibling, deduction %}}, switches cash_out, active, allow_custom_amount, allow_negative, show_negative, company_expense, tax_exempt, show_home_country (off unless true) and show_balance, allow_partial, requestable, show_amount (on unless false). Update sends every field again; apply_changes update|new with balance_date starts a new balance. action delete: policy_id (no ticket taken under it). action assign: policy_id; fields scope all|selected, employee_ids[], opening_balance (active employees in my payroll.manage scope). action unassign: policy_id, employee_id.

  Needs: payroll.manage payroll_setup.manage

  Parameters: company_id* action* policy_id employee_id fields * = required

• manage_air_tickets Changes data

  Air ticket transactions for employees in my payroll.manage scope (HR module). action add: fields employee_id, policy_id (one of the employee's policies; empty for the company allowance while no policies exist), slice (ZenHR's eligible slice: the index of one of the policy's slices from list_air_ticket_policies; default the one that fits the employee), tickets[] (ticket cards: {owner "self" or a family member id, count, amount (default count × the slice's ticket value)}) or the older owners[] ("self" and family member ids, one ticket each), travel_date, return_date, destination, cash_out (paid with the salary, when the policy allows), amount (the total; default the cards' amounts added up), notes; checked against the balance on the travel date. action mark_paid: fields ids[], paid_at, payment_reference (booked, unpaid ones). action delete: transaction_id (not paid and not in an approved payroll). action bulk_delete: fields ids[] (paid ones stay; returns how many were deleted).

  Needs: payroll.manage

  Parameters: company_id* action* transaction_id fields * = required

• manage_business_travel Changes data

  Change the business travel setup (payroll_setup.manage, HR module). action update_setup: fields trip_per_diem_type_id, trip_air_ticket_type_id, trip_accommodation_type_id (transaction type ids, required), trip_payment in_payroll|off_cycle, trip_remind_days (0-60), trip_expense_type_ids[], trip_slip_breakdown, trip_show_amounts, components[] {id, name_en, name_ar} (a listed component with both names empty is removed when no policy uses it). action create and update (policy_id): fields name_en (required), name_ar, position_ids[] (required), destinations[] {category domestic|international; domestic needs country, departure_cities and arrival_cities ("a,b"); international departure_countries[] and arrival_countries[] (codes); travel_types[] airplane|bus|car|train, air_classes[] economy|business|first, max_air_ticket, max_travel_cost, hotel_tiers[] 1-5, max_accommodation, components[] {type_id, amount, mandatory}}, switches active, requestable, notes_required, attachments_required (off unless true). action delete: policy_id.

  Needs: payroll_setup.manage

  Parameters: company_id* action* policy_id fields * = required

• manage_cost_allocations Changes data

  Cost center allocations for employees in my payroll scope (payroll.manage). action add: fields employee_id, start_date, end_date (optional, on or after the start), allocations[] {cost_center_id, percent} with distinct cost centers whose percentages add up to 100; an employee's periods can't overlap. action delete: allocation_id (the id list_payroll_costs kind cost_allocations shows); removes all its cost centers for that period.

  Needs: payroll.manage

  Parameters: company_id* action* allocation_id fields * = required

• manage_cost_center_groups Changes data

  Cost center groups (payroll_setup.manage). action save: a new group, or changes to one with group_id; fields name_en (required), name_ar (else the English name), code (optional group code). action delete: group_id; a group that still includes cost centers can't be deleted. Cost centers join a group from the cost centers setup form. list_payroll_costs kind cost_center_groups lists them.

  Needs: payroll_setup.manage

  Parameters: company_id* action* group_id fields * = required

• manage_eos_policies Changes data

  End-of-service (STB) policies (HR module, payroll_setup.manage), the same rules as the screen. action create / update (policy_id): fields name_en, name_ar, termination_category (any|resignation|termination|end_of_contract|retirement|other), min_years, tiers ("from-to:days" per line such as "0-5:15\n5-:30", or a list of {from_years, to_years, days_per_year}), worth_tiers (same form, the value a percent), contract_type both|limited|unlimited, exclude_unpaid[], nationalities[], end_date, allowance_type_ids[], calc_base calendar|365|360, year_definition calendar|fixed with fixed_year_days, calc_type service|remaining|both, remaining_direction add|deduct, service_min_salaries, service_max_salaries, remaining_min_salaries, remaining_max_salaries, flags tax_exempt, is_default (one default per category), thirty_day_months, distribute_per_slice, override_amount. action delete: policy_id (refused while a monthly provision uses it).

  Needs: payroll_setup.manage

  Parameters: company_id* action* policy_id fields * = required

• manage_exchange_rates Changes data

  Exchange rates (payroll_setup.manage). action save: fields from_currency, to_currency (ISO codes, different), rate (> 0), effective_date, optional reverse_rate (else 1 ÷ rate) and branch_id (empty = company-wide); saves the pair and its reverse, replacing a rate for the same pair, branch and date. action copy: fields branch_ids[] and effective_date; copies each pair's latest company-wide rate to those branches. action toggle: fields multi_currency true|false turns multi-currency on or off. action delete: rate_id. list_payroll_costs kind exchange_rates lists them.

  Needs: payroll_setup.manage

  Parameters: company_id* action* rate_id fields * = required

• manage_finance Changes data

  Financial transactions, loans, salary packages and salary stop for employees in my payroll scope (payroll.manage). action add_transaction: fields employee_id, transaction_type_id (or type earning|deduction with category), amount, month YYYY-MM or effective_date YYYY-MM-DD (then the payroll month it falls in, after the cut-off the next one), description, off_cycle (then paid_cash, deduct_tax, amount_type total|net, mark_paid), extra_salary, is_net. action update_transaction: transaction_id and the same fields (an unpaid transaction added by HR). action delete_transaction: transaction_id (its month must be open). action add_loan: fields employee_id, loan_type_id, amount, currency (ISO code, default the company currency; payroll deducts each installment converted with the exchange rate of its month), installments or installment_amount, effective_date, first_installment_date (or start_month YYYY-MM), reason (notes), payout off_cycle|payroll. action delete_loan: loan_id (no repayments yet). action loan_details: loan_id (the loan with its installment schedule: id, position, amount, due_date, status unpaid|paid|skipped, cash, in_payroll, payroll_amount and exchange_rate in the payroll currency). action skip_installment / pay_installment_cash: loan_id, installment_id (an unpaid installment not in a payroll; a skipped one moves to the end). action reschedule_loan: loan_id; fields installment_amount or number_of_payments (what is still owed, from the first unpaid installment). action add_salary_package: employee_id; fields effective_on, basic_salary, salary_count (12-16), currency, ss_salary, company_bank_account_id, tax_number, ss_number, gl_account, notes, items[] {kind allowance|deduction|company_expense, transaction_type_id or name_en/name_ar, amount}. action withdraw_salary_package: employee_id, package_id (not started yet). action stop_salary (fields reason) and resume_salary: employee_id. Attachments go through the API or the screen. action bulk_delete_transactions: ids (unpaid regular-payroll transactions; off-cycle and approved months are skipped). action next_month: transaction_id moves to the next payroll month. action settle_off_cycle: ids of unpaid off-cycle transactions marked paid.

  Needs: payroll.manage

  Parameters: company_id* action* employee_id transaction_id loan_id installment_id package_id ids fields * = required

• manage_insurance Changes data

  Medical insurance (HR module), the same rules as the screen. action create_policy / update_policy (policy_id) (payroll_setup.manage): fields insurer, policy_number, start_date, expiry_date (after the start), cost_adult, cost_minor, currency_adult, currency_minor, branch_id (empty = all branches), pro_rata, per_employee. action delete_policy (payroll_setup.manage): policy_id. action add_member (payroll.manage, employee in my scope): policy_id; fields employee_id, family_member_id (one of the employee's family, empty = the employee), offline_insurance_id, start_date, end_date, adult_dependents, minor_dependents, custom_setup with custom_cost, monthly_deduction; the same owner again updates their row. action remove_member (payroll.manage): member_id.

  Needs: payroll.manage payroll_setup.manage

  Parameters: company_id* action* policy_id member_id fields * = required

• manage_overtimes Changes data

  Manage Overtimes for employees in my payroll scope (payroll.overtime.manage, which payroll.manage grants). action add: fields employee_id, overtime_type_id, date (YYYY-MM-DD, not in the future), from_time and till_time (HH:MM) or hours, reason; it is approved at once and paid with the open payroll month. action update: overtime_id, the same fields without employee_id (refused once paid in an approved payroll or converted to time off). action convert_to_time_off (ZenHR's Overtime Converter): fields from, to, leave_type_id, rate (% of the hours), effective_date, minimum_hours, combined, notes, optional department, work_location, section, main_project; approved, unconverted overtime not yet in an approved payroll becomes leave balance (off until legally validated). action batch_as_income: fields employee_id, transaction_type_id (an earning type), overtime_type_id, hours, date, description: hours × the employee's overtime rate as an earning in the open payroll month. GET /overtimes on the API lists them.

  Needs: payroll.manage

  Parameters: company_id* action* overtime_id fields * = required

• manage_part_time Changes data

  Part-time transactions for employees in my payroll scope (payroll.manage). action add: fields employee_id, transaction_type_id (a part-time transaction type), amount (else the type's default amount, times recurring_value when given; required when it has none), recurring_value (ZenHR's "Recurring": the number of units), net (true: the amount is net and grossed up for tax), effective_date, end_date (optional), recurring true (paid every month from the date) or false (once), note. action update: assignment_id and the same fields without employee_id. action delete: assignment_id. list_payroll_costs kind part_time lists them.

  Needs: payroll.manage

  Parameters: company_id* action* assignment_id fields * = required

• manage_payroll_run Changes data

  Payroll runs (payroll.manage). action calculate: Manage salaries → Calculate (fields salary_type monthly|extra, month YYYY-MM, picks[] from list_payroll_costs kind calculate_options: branch:<id>, employee:<id>, org:<id>, anyone matching one is calculated, none = everyone not paid yet; monthly: period_from / period_to YYYY-MM-DD (default: the cut-off range), batch_id to add to a draft batch of the month instead of a new one, move_pending true to move this month's transactions dated after period_to to next month; extra: title, percent_of_basic). action run: calculate a month (fields month YYYY-MM; optional batch departments[], branches[], employees[] ids). action off_cycle: an extra payment (fields title, month, percent_of_basic). action recalculate, approve (approved at once, or sent through the salary batch approval chain: result approved or sent), paid (fields paid_at, payment_reference) and delete (a draft) take run_id. action adjust: a one-off amount on a draft payslip (payslip_id; fields adjustment, note). action remove_employee: Delete on a salary row, takes the employee of payslip_id out of draft run_id (recalculating leaves them out). action revert_check: whether approved run_id can go back to draft (can_revert, blockers). action revert: Revert to draft, undoing what approving did (installments unpaid, loans active again, provisions as before); refused while blockers exist (fields reason). action settlement_candidates: leavers in scope whose leaving month has no slip yet (employee_id, employee_number, employee_name, terminated_on, month). action off_cycle_settlement: ZenHR's Off-Cycle Settlement slip, the leaver's final settlement worked out on its own as a draft one-person batch of the leaving month (fields employee_id; refused when the month already has their slip); approve it with action approve.

  Needs: payroll.manage

  Parameters: company_id* action* run_id payslip_id fields * = required

• manage_payroll_setup Changes data

  Change payroll setup (payroll_setup.manage), the same as the screens. action update_settings: section payroll_setup | in_advance | extra_salaries | tax_setup | journal | provision_setup, fields = only the settings to change (names and value shapes as list_payroll_setup kind settings gives them; the others keep their values; e.g. journal fields je_type summary|detailed, je_match_levels[], acct_* codes; extra_salaries es_reimburse_type_id is required when es_reimburse_tax is on). action add_rule / update_rule (id) / delete_rule (id): section social-security (name_en, name_ar, employee_percent, employer_percent, salary_from, salary_to, floor (ZenHR minimum salary: the least SS wage charged), ceiling, base basic|gross, min_work_days, effective_from, effective_to, active, external_ref), tax (name_en, name_ar, effective_from, effective_to, bracket_rows [{min, max, rate, extra_exemption}] with bracket_period monthly|annual, or brackets "from:rate" per line, personal_exemption, family_exemption, other_exemption, notes, external_ref), extra-salaries (name_en, name_ar, percent, base basic|gross, distribution once|monthly, pay_month 1-12, prorate, taxable, in_final_settlement, active), bank-accounts (bank_name, account_number, iban, bank_branch, account_name, country, currency, exchange_account, establishment_number, branch_id, bank_export_template_id, is_default), bank-templates (name_en, name_ar, kind, bank, extension, delimiter, header_lines, footer_lines, columns_text "field|Header" per line, date_format, amount_decimals, include_header, active) or slip-templates (slip_type, language, header, footer); update_rule takes the whole record (a switch left out is off); an item in use can't be deleted. action update_ss_salaries: fields.base basic|gross sets the SS salary of the active employees in my payroll.manage scope.

  Needs: payroll.manage payroll_setup.manage

  Parameters: company_id* action* section id fields * = required

• manage_project_contributions Changes data

  Per-project contribution percentages of an employee in my payroll scope (docs/payroll-project-contributions.md), as GET/PUT /employees/{id}/project-contributions. action get (payroll.view or payroll.manage): employee_id, optional month YYYY-MM; returns total, complete (adds up to 100) and projects[] {assignment_id, project_id, project, code, contribution_percent, hours (approved timesheet hours that month), hours_share (% of the month's hours)}. action set (payroll.manage): employee_id, projects[] {project_id, contribution_percent} for the projects the employee is assigned to, adding up to exactly 100 (a project left out gets 0). The Calculated Costs report by project and the Project Summary report split salaries by these.

  Needs: payroll.manage payroll.view

  Parameters: company_id* action* employee_id* month projects * = required

• manage_provisions Changes data

  Monthly provisions (payroll.manage), the same as the screen. action calculate: month YYYY-MM, or from + to (YYYY-MM, up to 24 months, worked out oldest first), for every employee or only those picked by any of employee_ids, job_role_ids, department_ids, work_location_ids, section_ids, project_ids, hierarchy_group_ids, business_unit_ids, division_ids, segment_ids (id lists), work_type and contract_type (limited | unlimited); follows provision setup and replaces what those months had for them; gives the number of employees. action delete_month: month, deletes that month's provisions of the employees in my payroll.manage scope. action bulk_delete: ids (provision row ids); only an employee's latest month can go, so deleted can be less than chosen. Provision setup is manage_payroll_setup update_settings section provision_setup.

  Needs: payroll.manage

  Parameters: company_id* action* month from to work_type contract_type ids employee_ids job_role_ids work_location_ids department_ids section_ids project_ids hierarchy_group_ids business_unit_ids division_ids segment_ids * = required

• manage_salary_package_templates Changes data

  Salary package templates (ZenHR Salary Package Templates, payroll.manage), the same rules as the screen. action create: fields name_en, name_ar, basic_salary, active (default true), external_ref (the ZenHR id). action update (template_id): only the fields to change. action delete (template_id). action add_item (template_id): fields type allowance|deduction, transaction_type_id or name_en/name_ar, amount. action remove_item (template_id, item_id). An inactive template isn't offered when applying a template to an employee. list_payroll kind templates lists them.

  Needs: payroll.manage

  Parameters: company_id* action* template_id item_id fields * = required

• manage_salary_scales Changes data

  Salary scales (HR module), the same rules as the screen. Setup actions need payroll_setup.manage. action create_scale / update_scale (scale_id): fields name_en, name_ar, has_grades, has_bands, has_levels (at least one), salary_range_layer, benefits_layer, timeoffs_layer (grade|band|level, a layer the scale has), exceed_range_percent, exceed_benefits_percent, compa_from, compa_to, activation_date YYYY-MM-DD, status active|inactive|draft, auto_move_vacations. action delete_scale: scale_id (refused while an employee sits on it). action add_layer / update_layer (layer_id): scale_id, layer grade|band|level; fields name_en, name_ar, scale_grade_id (band, level), scale_band_id (level), min_salary, mid_salary, max_salary, entitled_to_overtime, and id lists job_role, loan_type, air_ticket_policy, insurance_policy, annual_leave, sick_leave (a list sent replaces the old one), allowances [{transaction_type_id, amount}]. action delete_layer: scale_id, layer, layer_id (refused while in use). action update_job_grade: grade_id; fields ideal_compa_ratio (0.5-1.5), benefits, leave {leave_type_id: days}. action add_job_grade_level: grade_id; fields name_en, name_ar, rank, salary. action delete_job_grade_level: level_id. action set_enforcement: fields salary_scale_enforce off|block. action place_employee (payroll.manage, employee in my scope): employee_id; fields scale_level_id, scale_band_id, scale_grade_id (all empty = off the scale); returns a warning when the salary is outside an enforced range.

  Needs: payroll.manage payroll_setup.manage

  Parameters: company_id* action* scale_id layer layer_id grade_id level_id employee_id fields * = required

• manage_stb_encashments Changes data

  End-of-service benefit encashments (HR module), the same rules as the screen. action create (payroll.stb_encashments.manage, which payroll.manage grants; employee in my scope): fields employee_id, amount (at most what list_stb_encashments kind available allows), payment payroll|off_cycle, notes; it adds an earning to the open payroll month (paid now when off_cycle). action delete (payroll.manage): encashment_id, while its payroll month is not approved and it was not paid off-cycle. action settings (payroll_setup.manage): fields = only the settings to change (the others keep their values): stb_encash_enabled, stb_encash_max_percent (0-100), stb_encash_min_years, stb_encash_every_years, stb_encash_min_amount, stb_encash_max_amount, stb_encash_after_months (after the hiring date), stb_encash_times per stb_encash_per_years, stb_encash_eligible all|citizens|non_citizens, stb_encash_attachments_required, stb_encash_notes_required, stb_encash_requestable, stb_encash_default_payment payroll|off_cycle, stb_encash_limited_policy_id / stb_encash_unlimited_policy_id (STB policy ids), stb_encash_income_name_en/_ar, stb_encash_deduction_name_en/_ar. create also takes external_ref (the ZenHR id); payment defaults to stb_encash_default_payment.

  Needs: payroll.manage payroll_setup.manage

  Parameters: company_id* action* encashment_id fields * = required

• payroll_lists Changes data

  The payroll list screens (docs/payroll.md), read through the API so filters and scope are the same. action requests (list air-tickets|business-trips|expenses|missing-punches; payroll.view or the list's sub-module, e.g. payroll.expenses.view): requests with details and whether payroll paid them, filters in filters (status, from, to, travel_policy, travel_from, travel_to, expense_name, page). action screening (payroll.view): salary packages screening, filters active_employees, effective_from, effective_to, approval_status, package_status, page. action package (payroll.view): employee_id and package_id with totals and the package before it. action add_amortized (payroll.expenses.manage): fields employee_id, type earning|deduction, amount, months 2-60, start_month YYYY-MM, description.

  Needs: payroll.manage payroll.view

  Parameters: company_id* action* list employee_id package_id filters fields * = required

• review_payroll_run Reads only

  The review of a payroll run: its totals, last month's and who joined, left or changed, only for the people you reach and the amounts open to you. Approve or return it with run_section_action on payroll_runs (docs/mobile-payroll.md).

  Needs: employees.view_sensitive

  Parameters: company_id* run_id* * = required

Reading and changing any section the way the mobile app does, with the same permissions and field levels.

Try asking: «Show my app menu» «List the records of this section»

• app_dashboard Changes data

  The dashboard the mobile app draws for you: the widgets you may see, as blocks (stat, chart, list, card), each with what it opens in the app. action read returns them, with the optional filters period (this_month, last_month, last_30, this_quarter, this_year), from, to, branch_id and department_id. action save changes the order and what shows on the phone, without touching the web: order (keys), show (keys; the others are hidden), or reset (true) to follow the web again. A widget you may not see is refused.

  Needs: employees.view_sensitive

  Parameters: company_id* action* period from to branch_id department_id order show reset * = required

• describe_section Reads only

  What an engine section is made of for you: its columns, filters, record fields, forms, actions and blocks, each with its permission. What is closed to you isn't listed (docs/mobile-engine.md).

  Needs: employees.view_sensitive

  Parameters: company_id* section* * = required

• get_app_navigation Reads only

  The mobile app's menu for you: the web menu filtered by license and permission, each item opening an engine section or one of the app's own screens. pending counts the menu items the app has no screen for yet.

  Needs: employees.view_sensitive

  Parameters: company_id* * = required

• read_section Reads only

  Reads an engine section: part=records (a list, with search, filters, sort, page), record (one, with its field_levels and actions), form (a form's starting values), options (choices of a field), blocks (cards and charts), export (the list as CSV text) or file (a record's file, in base64: a copy, so it needs documents.download). A hidden value isn't in the answer. A section under a record needs parent.

  Needs: documents.download

  Parameters: company_id* section* part* record_id parent field search sort direction page per_page filters * = required

• resolve_app_link Reads only

  What a notification's or a search result's link opens in the mobile app for you: status open with its target (an engine section or one of the app's screens, with the record), closed with the reason (permission, not_found, web_only) and a message, or none when there is no link. Checks your permissions and the record itself.

  Needs: employees.view_sensitive

  Parameters: company_id* url * = required

• run_section_action Changes data

  Does an action of an engine section on one record (record_id) or on up to 100 (ids): archive, restore, delete and others, as describe_section lists them for you. An action not listed for you is closed. With ids, each record is checked alone and the answer says which failed.

  Needs: employees.view_sensitive

  Parameters: company_id* section* action* record_id ids parent input * = required

• save_section_record Changes data

  Adds (no record_id) or changes a record of an engine section. Send only what changes, in values, by the keys describe_section gives. What you can't edit is dropped and named in ignored; send version from the record to refuse overwriting a newer change. Files go through the API.

  Needs: employees.view_sensitive

  Parameters: company_id* section* record_id parent values* version * = required

Listing and running the reports your role allows, large reports in the background, custom and saved reports.

Try asking: «Run the headcount report» «Which reports can I run?»

• list_reports Reads only

  The reports the person may run (each needs its permission: employees.view for people reports, leaves.view for time off, attendance.view for attendance and timesheets, payroll.view for pay, costs and bank exports, requests.view and assets.view for those), the ones coming with a module, their saved options, and the customized reports when they have reports.custom. With report, that report's form: filters (key, type, params to send, options), columns by group, default columns, switches and exports.

  Needs: assets.view attendance.view employees.view leaves.view payroll.view reports.custom requests.view

  Parameters: company_id* report * = required

• manage_custom_report Can delete

  Customized reports (reports.custom), as POST/PATCH/DELETE custom-reports. action sources: the data sources and fields the person may pick (each source needs its permission; IDs and passports need employees.view_sensitive). action save: create, or change with id: fields name {en, ar}, locale en|ar, employee_status active|inactive|both, schedule none|daily|weekly|monthly|annually, notify_user_ids (only people who work in the report's branch and may open customized reports are kept), columns ["source.field", …] in order, shared_branch_ids (ZenHR's "Choose the branches…": other branches that may open it, only branches you work in; each viewer sees only the data their own access reaches). A report belongs to the branch it was made in; one shared with your branch can be run but changed only by its own branch. action delete: remove it with id. Run one with run_report and custom_report_id.

  Needs: employees.view_sensitive reports.custom

  Parameters: company_id* action* id fields * = required

• manage_saved_report Can delete

  The person's saved report options ("Save selected options"), as POST /reports/{report}/saved and DELETE /saved-reports/{id}. action save: report (key), name, options (the run_report filters, cols, show); the same name replaces. action delete: id. Run saved options with run_report and saved_id.

  Needs: employees.view_sensitive

  Parameters: company_id* action* report name options id * = required

• queue_report Changes data

  Large reports in the background (docs/reports.md), the same as POST /reports/{report}/queue and GET /me/report-files. action queue: report (a key from list_reports), format xlsx|csv, filters (as run_report) or saved_id; the file is built as you, in your current branch workspace, and you get a notification when it is ready. action list: your files with status (queued, running, ready, failed), row_count and download_path (GET it with your API token). action show: one file by id.

  Needs: employees.view_sensitive

  Parameters: company_id* action* report format filters saved_id id * = required

• run_report Reads only

  Runs a report for the employees in the person's scope, the same as the screen and GET /reports/{report}/run. report: a key from list_reports. filters: the filter params (multi filters as arrays of ids or values, dates YYYY-MM-DD, date ranges as key_from / key_to, months YYYY-MM), plus cols (column keys), show (switch keys) and show_zero. saved_id starts from saved options. Or custom_report_id to generate a customized report (reports.custom). limit: rows per table, 100 by default, 2000 at most. Returns the columns, rows, totals (and sections for sectioned reports) and the row count.

  Needs: reports.custom

  Parameters: company_id* report filters saved_id custom_report_id limit * = required

The figures on your dashboards, and the company's holidays.

Try asking: «When is the next public holiday?»

• get_dashboard Reads only

  A dashboard's figures, the same as on the screen (docs/dashboards.md), for the employees in the person's scope. section hr: the Home Page, built from the widget registry; only the widgets the person may see are computed (each needs its section's permission: headcount, charts and contracts employees.view, documents employees.view_sensitive, time off leaves.view, attendance attendance.view, payroll cost payroll.view, recruitment recruitment.view, field jobs field.jobs.view, and the person's own cards self.*), a part none of them needs is null; widgets narrows it to some keys (see manage_my_dashboards home_widgets); filters: period (this_month, last_month, last_30, this_quarter, this_year) or from/to (YYYY-MM-DD), branch_id, department_id; kpis carry value, previous (the period before) and change in percent. attendance (attendance.view: today, the last 14 days, most late and absent this month), payroll (payroll.view: latest regular run totals, six months, basic salary ranges, recent runs, loans), assets (assets.manage: by status, type and department, value, a year of purchases, expiring soon). Amounts are in the company currency.

  Needs: assets.manage attendance.view employees.view employees.view_sensitive field.jobs.view leaves.view payroll.view recruitment.view

  Parameters: company_id* section* widgets period from to branch_id department_id * = required

• get_holiday_calendar Reads only

  A month of the company's holidays (each with its first and last day), the next holidays, and with leaves.view who in the person's scope is on approved leave that month (otherwise leaves is null). month is YYYY-MM, this month by default.

  Needs: employees.view leaves.view self.holiday_calendar

  Parameters: company_id* month * = required

Your evaluations and goals, evaluation cycles, OKRs, 360° feedback, succession planning and the 9-box grid.

Try asking: «Which evaluations are waiting for me?»

• get_my_performance Reads only

  My performance: my evaluations (scores hidden until complete), the evaluations waiting for my review, my goals, the 360° feedback requests I owe and my feedback forms.

  Needs: self.performance.goals self.performance.review self.performance.view

  Parameters: company_id* * = required

• get_performance_kpis Reads only

  The performance KPI dashboard (performance.view or .manage, their scope): for a cycle (cycle_id, default the latest) and optional branch_id / department_id: completion by stage, average scores by branch, department and position, the score distribution, goal and OKR progress, top and bottom performers, and overdue evaluations.

  Needs: performance.manage performance.view

  Parameters: company_id* cycle_id branch_id department_id * = required

• list_evaluations Reads only

  Evaluation cycles and evaluations. With evaluation_id: one evaluation with criteria, scores, notes and OKRs (the employee, their task holders, or performance.view/manage over them). With cycle_id: the cycle and its evaluations in scope, filtered by q, branch, position, work_location, department, section, project, hierarchy_group, stage (writing_okrs, auditing_okrs, self_assessment, evaluation, auditing_results), status (in_progress, completed), action (yes: the caller holds the current task), okrs (published, not_published), missing (yes, no), employee_status (active, inactive). Otherwise the cycles, filtered by q (name), status (draft, open, closed) and stage (current stage) (performance.view, performance.manage or performance_setup.manage).

  Needs: performance.manage performance.view performance_setup.manage

  Parameters: company_id* evaluation_id cycle_id q branch position work_location department section project hierarchy_group stage status action okrs missing employee_status * = required

• manage_calibration Can delete

  Calibrating evaluation results (performance.calibrate, docs/talent-mobile.md). action board (cycle_id): who sits in which result band, and whose result you may move. action history (evaluation_id): the moves of one result. action move (evaluation_id): fields score (0 to 100), reason; only a completed evaluation in an open cycle, in your scope, never your own. The employee, the result writer and others who may calibrate are told.

  Needs: employees.view_sensitive

  Parameters: company_id* action* cycle_id evaluation_id fields * = required

• manage_evaluation_cycle Changes data

  Evaluation cycles (performance.manage). action create: fields evaluation_template_id, name, branch_ids, year, evaluation_part (Y, H1–H2, Q1–Q4 or M1–M12 by the template period), stages {writing_okrs|auditing_okrs|self_assessment|evaluation|auditing_results: {start, end}} (evaluation required). With cycle_id: launch (an evaluation for each active employee, weights must make 100), close, dates (fields.stages), add_employees (fields.employees ids), delete (drafts). With evaluation_id, for an employee in scope: task_holders (fields okr_writer_id, okr_auditor_ids, result_writer_id, result_auditor_ids: employee ids), evaluation_dates (fields.stages), remove.

  Needs: performance.manage

  Parameters: company_id* action* cycle_id evaluation_id fields * = required

• manage_feedback Changes data

  360° feedback and feedback forms. For everyone: submit (request_id; fields scores {criterion id: 1–5}, comment; on a survey cycle fields answers {question index: 1–max or text}), open_form (assignment_id: a form assigned to me with its questions and my answers), answer_form (assignment_id; fields.answers {question id: value}), results (cycle_id, employee_id: HR any time, the employee once closed, and their direct manager when the cycle allows; survey cycles add overall, the weighted score). For performance.manage: list_cycles, create_cycle (fields name, evaluation_template_id, due_date, peers_per_employee; or ZenHR's survey cycle: name, description, start_date, due_date, manager_sees_results, groups {manager: {weight}, report: {count, weight}, peer: {count, weight}, self: {}} with weights adding up to 100, assign_to individual with employees ids or group with group {...}, and questions [{type rating|open, text, helper, required, max 2–10, low, high}] or starter general|leadership|customer|culture), show_cycle, launch, close, delete_cycle (cycle_id); list_forms, create_form (fields title, description, start_date, end_date, anonymous, questions [{type text|textarea|checkbox|radio|rating|yes_no, label, helper, mandatory, options [{label, value}], min_rating, max_rating}], assign_to individual with employees ids or group with group {branch, position, department, work_location, work_type}), show_form, delete_form (form_id).

  Needs: performance.manage performance.view

  Parameters: company_id* action* cycle_id employee_id request_id assignment_id form_id fields * = required

• manage_goals Changes data

  Goals. action add: fields title, description, due_date, and employee_ids (performance.manage over them; default: myself). action update: goal_id, fields progress 0–100, status open|achieved|missed (the owner or HR). action delete: goal_id (whoever set it, or HR).

  Needs: performance.manage

  Parameters: company_id* action* goal_id fields * = required

• manage_nine_box Changes data

  The 9-box grid (performance × potential, docs/succession.md). action grid (performance.view or .manage, their scope): filters cycle_id, branch_id, department_id, position_id, box (1–9; 1 low/low, 9 high/high) → each box with its employees, and those not placed yet. action history: employee_id → their box in each cycle and their potential assessments. action assess (performance.manage over the employee, or their direct manager): fields employee_id, rating (low|medium|high), criteria {learning_agility, leadership, drive, adaptability, aspiration: 1–5}, notes, evaluation_cycle_id, assessed_on. action delete_assessment: assessment_id.

  Needs: performance.manage performance.view

  Parameters: company_id* action* cycle_id branch_id department_id position_id box employee_id assessment_id fields * = required

• manage_okrs Changes data

  An employee's OKRs in a cycle, for their OKR writer, OKR auditors, result writer or performance.manage over them, while unpublished. action save_objective: evaluation_id (new) or objective_id (change), fields name {en, ar}, description {en, ar}, weight, key_results [{name {en, ar}, weight, measurement_unit_id, target}] (weights make 100). action delete_objective: objective_id. action publish: evaluation_id (objectives must make 100%). action mass_assign: template_id (OKR template), fields.evaluations (ids).

  Needs: performance.manage

  Parameters: company_id* action* evaluation_id objective_id template_id fields * = required

• manage_performance_setup Changes data

  Performance setup. action list (performance.view/manage/setup): kind evaluation-templates, general-factor-templates, okr-templates, rating-types, categories, levels, competencies or position-competencies. The rest need performance_setup.manage; id changes an existing record. save_template (fields as on the template form: name {en, ar}, period, result_format, branch_ids, self_assessment, max_okrs, general_factor_template_id, okrs_creator, okr_auditors [supervisor|manager_1|manager_2|key_staff], result_writer, result_auditors [same], self_assessment_stage, okr_followup, evaluate_based_on objectives|key_results, factors {okrs|general_factors|competencies: {active, weight}}, scales [{name, min, max}], active), delete_template, add_criterion (id = template; title {en, ar}, weight, kind factor|okr, target, measurement_unit_id), delete_criterion, save_factor_template (name, branch_ids, factors [{name, weight}]), delete_factor_template, save_okr_template (name), delete_okr_template, save_template_objective (id = OKR template, index to replace; the objective fields), delete_template_objective (id, index), save_rating_type (name, units [{id?, name}]), delete_rating_type, save_category (name, levels, linked_to_position), save_level (name, rank), save_competency (name, description, competency_category_id), delete_category, delete_level, delete_competency, link_position (position_id, competency_id, required_level, weight), unlink_position. action rate_competency (performance.manage or the line manager): employee_id, competency_id, level.

  Needs: performance.manage performance.view performance_setup.manage

  Parameters: company_id* action* kind id index fields * = required

• manage_succession Changes data

  Succession planning (succession.manage, limited to its scope). action list: key positions with successors and whether each is critical (high risk, high impact, nobody ready now). action save: key_position_id to change, fields title {en, ar}, position_id, department_id, holder_id, risk_of_loss and impact (low|medium|high), notes. action delete: key_position_id. action add_successor: key_position_id, fields employee_id, readiness (ready_now|one_two_years|three_plus_years), development_plan. action remove_successor: successor_id.

  Needs: succession.manage

  Parameters: company_id* action* key_position_id successor_id fields * = required

• review_evaluation Changes data

  Fill in an evaluation. action self (the employee, while in self review) or review (the result writer or performance.manage over the employee; completes it with the weighted score): fields scores {criterion id: 1–5}, actuals {template OKR criterion id: number reached}, kr_actuals {key result id: number reached}, comment; self also takes self_performance_summary, self_key_strengths, self_weaknesses, self_recommendations. action notes (result writer or HR): performance_summary, key_strengths, weaknesses, recommendations. action final (a result auditor or HR, once complete): final_rate_override 0–100, final_notes, notify_people.

  Needs: performance.manage

  Parameters: company_id* evaluation_id* action* fields * = required

• succession_intelligence Changes data

  Succession intelligence (succession.manage, its scope; docs/succession.md). action coverage: key positions with risk flags (vacant, single_incumbent, high_risk, high_impact, no_successors, no_ready_successor), exposure (critical|exposed|watch|covered), bench and bench strength, and the summary; filters exposure, department_id. action suggestions: key_position_id, limit → candidates ranked by a score out of 100 with each part (competency_fit, performance, potential, readiness, tenure), the weights, gaps and a suggested readiness. action explain: key_position_id, employee_id → why (rule-based, or the AI provider's text when it is set). action successor: successor_id → readiness history and development plan. action draft_plan: successor_id, apply (true saves the actions). action save_action: successor_id or action_id, fields title, kind (training|mentoring|assignment|project|other), owner_id, due_date, status (planned|in_progress|done), progress 0–100, competency_id, notes. action delete_action: action_id. Readiness itself is set with manage_succession add_successor.

  Needs: succession.manage

  Parameters: company_id* action* key_position_id employee_id successor_id action_id exposure department_id limit apply fields * = required

Job openings, candidates, interviews and offers.

Try asking: «How many candidates applied this month?»

• list_recruitment Reads only

  Recruitment (recruitment.view): kind summary (counts and the careers page address), jobs (filters status draft/open/closed, type, department, branch, q), job (job_id: the opening and its candidates by stage), candidates (filters job, stage applied/screening/interview/offer/hired/rejected, source, q), candidate (candidate_id: with notes and interviews), interviews (filters status, from, to, candidate). CVs download through the API.

  Needs: recruitment.manage recruitment.view

  Parameters: company_id* kind job_id candidate_id status type department branch job stage source candidate from to q * = required

• list_recruitment_ats Reads only

  Applicant tracking (recruitment.view; offers also recruitment.approve_offers): kind pipeline (the stages and who is in each; filter job), dashboard (funnel, time to hire, source effectiveness, offer outcomes; filters from, to, job), pool (talent pool; filters q on name/email/skills/tags, tag), offers (filter status), offer (offer_id: with both letters and the candidate's link while sent), availability (interviewers' weekly windows; filter employee), templates (stage emails, the "assessment" email, offer letter templates and their placeholders), assessments (candidate_id: the tests sent, status, best result, passed, gate, link), stage_assessments (the test each stage sends and its gate; and the active tests to pick from), settings (AI switches, candidate email language, connected accounts, job feed address).

  Needs: recruitment.approve_offers recruitment.manage recruitment.view

  Parameters: company_id* kind candidate_id offer_id from to job q tag status employee * = required

• manage_recruitment Can delete

  Recruitment (recruitment.manage). action save_job: post a job opening, or change one with job_id: fields title {en, ar}, department_id, branch_id, position_id, employment_type (full_time, part_time, contract, internship), description, requirements, positions, closing_date, status (draft, open, closed). action delete_job: an opening nobody was hired from. action add_candidate (job_id): fields name, email, phone, source (careers_page, referral, linkedin, job_board, other), cover_note. action update_candidate (candidate_id): fields stage (not hired), rejection_reason, rating 1–5. action delete_candidate. action add_note (candidate_id): fields body. action schedule_interview (candidate_id): fields interviewer_id (an employee), panel_ids, scheduled_at, kind (onsite, video, phone), duration_minutes, location, video_provider (zoom, google_meet, teams, manual), video_link; the candidate gets an invitation with an .ics. action update_interview (interview_id): fields status (scheduled, done, cancelled), rating, feedback. action hire (candidate_id): creates the employee record (needs employees.manage); fields employee_number, hire_date, branch_id, department_id, position_id, manager_id, basic_salary, create_login. action careers: fields enabled true/false turns the public careers page on or off. CV uploads go through the API or the screen.

  Needs: employees.manage recruitment.manage

  Parameters: company_id* action* job_id candidate_id interview_id fields * = required

• manage_recruitment_ats Can delete

  Applicant tracking (recruitment.manage unless noted), with fields in `fields`. Pipeline: move (candidate_id; stage, reason), bulk (ids, action move/reject/tag/untag/pool/unpool/email/delete, stage, reason, tags, template), profile (candidate_id; tags, in_talent_pool, linkedin_url), email (candidate_id; template = a stage), pool_add (name, email, phone, linkedin_url, tags, source, cover_note), add_to_job (candidate_id; job_opening_id). AI (only when the platform has a key and the company turned AI on; candidate data needs the company's consent): ai_parse (candidate_id), ai_match (candidate_id), ai_rank (job_id; refresh), ai_questions (job_id; count), ai_draft (title, department, employment_type, notes). LinkedIn: linkedin (job_id): posts to the connected page or returns the share link. Interviews: booking_link (candidate_id; interviewer_id, panel_ids, kind, duration_minutes, location, video_provider, video_link, booking_from, booking_to), availability (employee_id; windows [{weekday 0-6, starts_at, ends_at}]), scorecard (interview_id; your own as a panel member: ratings [{criterion, rating}], overall, recommendation strong_yes/yes/no/strong_no, notes). Offers: offer_draft (candidate_id; offer_template_id, salary_package_id, job_title, start_date, basic_salary, currency, items, expires_on, language), offer_update (offer_id), offer_submit, offer_send, offer_withdraw (offer_id), offer_decide (offer_id; decision approve/reject, note; needs recruitment.approve_offers), offer_convert (offer_id; employee_number, branch_id, department_id, boarding_template_id; needs employees.manage). Assessments: send_assessment (candidate_id; assessment_id, due_date Y-m-d, pass_stage, fail_stage, locale): sends a test link by the "Assessment" email, with an optional gate that moves the candidate on a pass or a fail; stage_assessments (fields {stage: {assessment_test_id (null removes), auto_send, pass_stage, fail_stage, due_days}}): the test a stage sends when a candidate enters it. Setup: email_template (stage, or "assessment" for the test link email with {test_name} {assessment_link} {due_date} {time_limit}; subject, body, auto_send), offer_template (template_id to change; name, body, active), offer_template_delete (template_id), settings (ai_enabled, ai_candidate_data, ai_auto_parse, recruitment_email_language).

  Needs: employees.manage recruitment.approve_offers recruitment.manage

  Parameters: company_id* action* candidate_id job_id offer_id interview_id employee_id template_id stage fields * = required

Your tests, the question bank, inviting people, grading and results.

Try asking: «Which tests do I need to take?»

• list_assessments Reads only

  Assessments (pre- and post-employment tests). kind mine: the signed-in employee's own tests (anyone). Needs assessments.manage or assessments.grade: summary (counts, pass rate), invitations (filters test, status pending/started/completed/cancelled, candidate, employee; candidates' links included), attempt (attempt_id: every answer with the right one, points and the anti-cheating log), grading (attempts waiting for a person), results (test_id: every attempt and how each question did), export (test_id: every attempt as a CSV file, as GET .../assessments/tests/{test}/export; returns filename, mime, size and base64). Needs assessments.manage: categories, questions (filters category, type, difficulty, active, q), question (question_id), tests (filters status, purpose, q), test (test_id, with items), templates (the ready test library).

  Needs: assessments.grade assessments.manage self.assessments

  Parameters: company_id* kind question_id test_id attempt_id category type difficulty active status purpose test candidate employee q * = required

• manage_assessments Can delete

  Assessments. action grade (answer_id; needs assessments.grade or assessments.manage): fields points (0 to the question's points), note, reason (required when changing a grade already given, the automatic one too; kept in the attempt's grade_history). Every other action needs assessments.manage. save_category (category_id to change): fields name {en, ar}, description, competency_id. delete_category. save_question (question_id to change): fields type (single, multiple, true_false, short_text, long_text, ordering, matching, numeric, file_upload), assessment_category_id, difficulty (easy, medium, hard), prompt {en, ar}, options [{key?, text {en, ar}}] (choices, items in the right order, or the left side of matching), targets (the right side of matching), answer (single: a key; multiple: keys; true_false: true/false; short_text: accepted answers; matching: {left key: right key}; numeric: {value, tolerance}), points, time_limit_seconds, explanation, is_active, media {name, content_base64} (an image jpg/png/gif/webp, audio mp3/m4a/wav/ogg or video mp4/webm, each within the upload_file_kb limit of company_limits; also options[n].media; options sent back with the same key keep theirs), remove_media (true), options[n].remove_media. delete_question. save_test (test_id to change): fields title {en, ar}, description, instructions, purpose (pre_employment, post_employment), time_limit_minutes, shuffle_questions, shuffle_options, attempts_allowed, pass_mark (%), negative_marking, negative_ratio, show_score, competency_id, pass_stage, fail_stage (recruitment stages), status (draft, active, archived), items [{kind: question, assessment_question_id} or {kind: random, assessment_category_id, difficulty?, draw_count}]. delete_test (only if nobody took it). invite (test_id): fields candidate_ids, employee_ids, expires_at, locale, pass_stage, fail_stage (the gate for candidates); returns the candidates' links. resend_invitation (invitation_id; fields expires_at, needed when the link has expired; returns sent and reason: sandbox, mail_off, employees_held, no_email, failed). cancel_invitation (invitation_id). install_template: fields key (from list_assessments kind templates).

  Needs: assessments.grade assessments.manage

  Parameters: company_id* action* category_id question_id test_id invitation_id answer_id fields * = required

Workflows for people joining, leaving, or going on and returning from long leave.

Try asking: «Show the onboarding of the new hires»

• download_workflow_pdf Reads only

  An onboarding, offboarding, clearance or resumption workflow as a printable PDF checklist (first-day details, tasks in order with assignee, due date and status, sign-off lines), as GET /api/v1/app/companies/{id}/boardings/{workflow}/pdf. My own workflow once sent, or one whose employee is in my employees.view scope. lang en|ar (Arabic is right to left). Returns filename, mime, size and the file as base64, plus the download link in the app.

  Needs: employees.view self.workflows

  Parameters: company_id* id* lang * = required

• list_workflows Reads only

  Onboarding, offboarding, vacation clearance and resumption workflows (docs/boarding.md). kind mine: the user's own sent workflows with their tasks (a resumption workflow on request starts when the vacation_resumption request is filed). kind workflows: workflows of the employees in employees.view's scope (filters category onboarding|offboarding|clearance|resumption, status pending|in_progress|completed, employee_id, date_from, date_to). kind workflow: one with its tasks (id). kind templates: workflow templates with their tasks (employee_settings.manage; filters category, q). kind template: one template with its tasks (id; employee_settings.manage).

  Needs: employee_settings.manage employees.view self.workflows

  Parameters: company_id* kind* id filters * = required

• manage_workflow Changes data

  Changes workflows (docs/boarding.md); the tasks themselves are completed with manage_task. employees.manage over the employee: send (employee_id; fields category onboarding|offboarding, boarding_template_id, and optionally boarding_date, arrive_by, location_name, contact_employee_id, manager_employee_id, description, sequential, tasks [{include, due_days}] in the template's order), mass_onboard (fields boarding_template_id, employee_ids, description, notes), cancel (id). employee_settings.manage: save_template (id to edit, or none to add; fields category, name {en, ar}, description, when_to_send on_date|before, days_to_send, arrive_by, location_name, contact_employee_id, sequential, min_vacation_days, leave_type_id, filters {field: [values]}, resumption_trigger first_punch|employee_request|auto_send, auto_adjust, notify_after_days, notify_user_ids (employee ids told with the employee when resumption tasks are still open), tasks [{kind, title, document_type_id, document_id, asset_type_id, assignee employee|person, assignee_employee_id, due_days, notes, notes_required, attachments_required, profile_fields}]), copy_template (id), delete_template (id).

  Needs: employee_settings.manage employees.manage

  Parameters: company_id* action* id employee_id fields * = required

Disciplinary actions, their rules and suspensions.

Try asking: «List this year's disciplinary actions»

• list_discipline Reads only

  Discipline data (docs/discipline.md) for the employees in scope. kind actions: disciplinary actions (discipline.view or manage; filters status approved|draft, employee_id, disciplinary_type_id, from, to). kind suspensions: suspensions with their request, resumption and cancellation states (HR in scope, or a manager up the line; filters employee_id, reason, status, resumption_status, from, to, resumption_from, resumption_to). kind setup: violation types, action types and escalation rules (discipline_setup.manage). Violation types and suspension reasons are edited with save_setup_form_item (entities disciplinary-types, suspension-reasons).

  Needs: discipline.view discipline_setup.manage

  Parameters: company_id* kind* filters * = required

• manage_discipline Changes data

  Disciplinary actions and their setup (docs/discipline.md). discipline.manage over the employee: action suggest (fields employee_id, disciplinary_type_id, incident_date: what the escalation rule prescribes); record (fields employee_id, disciplinary_type_id, incident_date, description, optional disciplinary_action_type_id, or action verbal_warning|written_warning|final_warning|deduction with deduction_amount when there is no rule; draft true to save for approval); approve (action_id of a draft); delete (action_id; refused once that month's payroll is approved); generate (fields leave_type_id, kind redundant|grace, effective_date, from, to, optional employee_id, branch_id, department_id: drafts from approved time off). discipline_setup.manage: save_action_type (optional id; fields name {en, ar}, deduction_type none|balanced_vacation|fixed|salary_day|percent, deduction_value, leave_type_id, transaction_type_id, allowance_type_ids, letter_template_id); delete_action_type (id); save_rule (optional id; fields disciplinary_type_id, name {en, ar}, rule_type sequential|separate, drop_after, drop_unit day|month|year, prevent_repetition, prevent_unit, action_type_ids in order); delete_rule (id); save_time_off (id: a time-off type; fields disciplinary_type_id for the generator, redundancy_interval day|week|month, exceed_actions and redundant_actions: rows {amount, rule_id, action_type_id}).

  Needs: discipline.manage discipline_setup.manage

  Parameters: company_id* action* action_id id fields * = required

• manage_suspension Changes data

  Employee suspensions (docs/discipline.md). HR (discipline.manage over the employee) acts at once; a manager up the employee's line asks, and the request follows the "Employee Suspensions & Resumptions" approval chain (HR without one). action create (fields employee_id, start_date, end_date, paid, suspension_reason_id, reason: notes, required unless the reason says otherwise). With suspension_id: decide (fields decision approve|reject, for the step it waits on), withdraw, resume (fields resumption_notes: come back early; HR's is approved at once), decide_resumption (decision), withdraw_resumption, cancel (HR at once, a manager asks), decide_cancel (decision, HR), cancel_resumption, decide_cancel_resumption (decision, HR), delete (HR, for one entered by mistake). Attachments go through the API or the screen.

  Needs: discipline.manage

  Parameters: company_id* action* suspension_id fields * = required

HR letters, their templates, documents to sign, and PDF copies.

Try asking: «Issue a salary certificate for me»

• download_letter_pdf Changes data

  An HR letter (kind letter, in the letter's language) or a signed document with its signature and audit trail (kind signature) as a PDF file, as GET /api/v1/letters/{id}/pdf and /api/v1/signatures/{id}/pdf. Only letters and signatures I may see, and the file needs documents.download for the letter's employee; a signature request not signed yet has no PDF. Returns filename, mime, size and the file as base64, plus the download link in the app.

  Needs: documents.download letters.manage letters.view self.letters.download self.signatures

  Parameters: company_id* kind id* lang * = required

• edit_letter_template Changes data

  The letter template editor (letters.manage; docs/letters.md), as /api/v1 letter-templates: action get: one template with its HTML body (template_id). action placeholders: what a body can have inserted ({name}, {salary}, … with their names, and {signature:ID} for active e-signatures). action upload_image: keep a picture (the logo, a stamp) in Mihnaro from data (a data: URL or base64, PNG, JPEG or GIF, within the letter_image_kb limit of company_limits) and name; put the returned url in the body as <img src="url" style="width: 30%">. action preview: the body (or template_id's) as its letter prints, filled for employee_id or with each placeholder shown by name; language ar|en. action preview_pdf: the same as a PDF file (base64). Save the body with save_letter_template.

  Needs: letters.manage

  Parameters: company_id* action* template_id body language employee_id addressed_to effective_date data name * = required

• issue_letter Changes data

  HR letters. action issue: a letter from letter_template_id for employee_id in your scope (letters.manage), addressed_to optional; a template that needs approval keeps it from the employee until someone else approves it. action generate: a self-service template for yourself. action confirm: confirm you received your letter (letter_id). action decide: approve or reject a letter waiting for approval (letter_id, decision approved|rejected; letters.manage, not one you issued). The text is filled from the template's placeholders.

  Needs: letters.manage self.letters.request

  Parameters: company_id* action* letter_template_id employee_id addressed_to effective_date letter_id decision * = required

• list_letters Changes data

  HR letters you may see: kind letters (yours once released, and those of the employees in your letters scope; the Manage HR Letters filters: employee_id, template, category, status sent, seen, pending, failed, unseen, unconfirmed, approved or rejected, classification, effective_from/effective_to, confirmation required/not_required/confirmed/unconfirmed, creator, created_from/created_to), templates (all for letters.manage, else the self-service ones you can generate), or signatures (documents sent to sign, yours and those in scope; status pending, signed or declined). With id, one letter or signature request with its text.

  Needs: letters.manage letters.view self.letters.view self.signatures

  Parameters: company_id* kind id status employee_id template category classification effective_from effective_to confirmation creator created_from created_to * = required

• save_letter_template Changes data

  Letter templates (letters.manage). action save: add one, or change it with template_id, sending fields: name {en, ar}, language ar|en, letter_category_id, body with {placeholders} (name, employee_no, job_title, department, branch, hire_date, salary, national_id, addressed_to, today, company; {signature:ID} prints an active e-signature from list_employee_settings e_signatures), active, is_draft, self_service, needs_confirmation, needs_approval, financial (a letter that shows pay: HR admins see it only where the branch allows; set by itself when the body uses {salary}, {salary_en} or {total_salary}). action duplicate: a draft copy. action favorite: star or un-star it for you.

  Needs: letters.manage

  Parameters: company_id* action* template_id fields * = required

• send_for_signature Changes data

  E-signatures. action send (letters.manage): send a document for employee_ids in your scope to read and sign, as title + body or an issued letter_id. action decline: decline to sign your own document (signature_id, decline_reason). Signing itself is done by the employee on the screen or the API, with their password and a drawn signature.

  Needs: letters.manage self.signatures

  Parameters: company_id* action* employee_ids title body letter_id signature_id decline_reason * = required

Assets, who holds them, and their types.

Try asking: «Which assets does Ali hold?»

• list_assets Changes data

  Company assets (assets.manage): filter by status (available, assigned, damaged, under_repair, archived), type (asset type id), owner (branch id or none), holder (employee id), expiry_from, expiry_to, q (name or serial number). With asset_id, one asset and its history. kind types lists the asset types instead.

  Needs: assets.manage

  Parameters: company_id* kind asset_id status type owner holder expiry_from expiry_to q * = required

• manage_asset Changes data

  Company assets and asset types (assets.manage). action save: add an asset, or change it with asset_id: fields asset_type_id, name, serial_number (unique), owner_branch_id, purchase_date, production_date, expiry_date, value, description, notes. action assign: hand it to an employee in scope (fields assigned_to, assigned_at, return_date, notes). action release: take it back. action status: fields.status damaged, under_repair, archived or available. action delete: an asset nobody holds. action save_type: an asset type, or change one with asset_type_id: fields name {en, ar}, branch_ids (ids or ["all"]), active. action delete_type: a type no asset uses. Attachments go through the API or the screen.

  Needs: assets.manage

  Parameters: company_id* action* asset_id asset_type_id fields * = required

Announcements, events, tasks and office TV screens.

Try asking: «Show the latest announcements» «What are my tasks?»

• get_announcement Reads only

  One company announcement in full: title and text {en, ar} (body_format html for ZenHR's rich text), publish date, author, ZenHR's recipient criteria (audience) and the targets enforced (only for those with announcements.manage or announcements.recipients) (targets: branches, departments, sections, positions, work_locations, projects, genders, religions, employees), start and expiry (scheduled), read_minutes, gallery (pictures in order with captions {en, ar}; url to read each), attachments (url to download a copied or uploaded file), and the ZenHR record it was imported from. Only one the person may read; another is "not found".

  Needs: announcements.manage announcements.recipients self.announcements

  Parameters: company_id* announcement_id* * = required

• list_announcements Reads only

  The company's announcements, pinned first then newest by publish date (imported ones in ZenHR's order), only those the person may read: the ones for everyone and the ones whose targets reach them (all of them with announcements.manage). q searches the title and text; show: pinned, current or expired.

  Needs: announcements.manage self.announcements

  Parameters: company_id* q show * = required

• list_events Reads only

  Company events: coming up, past, and a month (month YYYY-MM, default this one) as events by day with the company's holidays. Everyone in the company may read them.

  Needs: events.manage self.events

  Parameters: company_id* month * = required

• list_tasks Reads only

  Tasks. tab mine (default: given to me), assigned (given by me) or employees (tasks.manage: the people in scope); show pending (default), past_due, completed or all; status, kind, employee (id), template (id), q. With task_id, one task. kind_list templates lists the task templates (tasks.manage).

  Needs: self.tasks.view tasks.manage

  Parameters: company_id* task_id kind_list tab show status kind employee template q * = required

• manage_announcement Changes data

  Company announcements (announcements.manage). action save: publish one (the people it is for are notified), or change one with announcement_id: fields title {en, ar}, body {en, ar} (HTML as the composer makes it: p, h1-h4, strong, em, u, s, span/mark with color or background-color, ul/ol/li, blockquote, a, table, hr, img only with a picture uploaded by manage_announcement_media; anything else is removed), pinned, starts_on and expires_on (YYYY-MM-DD: shown from, until; a later start is announced on that day), gallery [{file, caption {en, ar}}] in order (first = cover) and attachments [{index} to keep one, {upload, name} to add one] (left out = unchanged), targets (who it is for: branches, departments, sections, positions, work_locations, projects (ids), genders (male, female), religions (muslim, christian, hindu, buddhist, sikh, other), employees (ids); several kinds narrow it, named employees are always added; {} = everyone), or the older branch_id alone (empty = company-wide; default the current branch). action delete: remove the announcement_id.

  Needs: announcements.manage

  Parameters: company_id* action* announcement_id fields * = required

• manage_announcement_media Changes data

  An announcement's pictures and files, uploaded into Mihnaro (announcements.manage; docs/communication.md §5ج). action upload: keep a picture (kind image, for the text or the gallery) or file (kind file: pdf, Word, Excel, PowerPoint, txt, csv or a picture), within the announcement_file_kb limit of company_limits, given as data (a data: URL or base64) and name; returns the file to put in manage_announcement's gallery [{file, caption}] or attachments [{upload: file, name}], or in the text as <img src="https://mihnaro-image.invalid/<file>">. On an announcement_id: gallery_add (data, name, caption {en, ar}), gallery_move (index, to), gallery_caption (index, caption), gallery_remove (index), attachment_add (data, name), attachment_rename (index, name), attachment_remove (index). Outside picture addresses are never accepted.

  Needs: announcements.manage

  Parameters: company_id* action* announcement_id kind data name caption index to * = required

• manage_event Changes data

  Company events (events.manage). action save: add one, or change one with event_id: fields title {en, ar}, date, start_time (HH:MM), location, description, branch_id (empty = company-wide; default the current branch). action delete: remove the event_id.

  Needs: events.manage

  Parameters: company_id* action* event_id fields * = required

• manage_task Changes data

  Tasks. action assign: fields kind (custom, document_upload, document_download, give_asset, take_asset, add_bank_account, add_family_member), title, description, due_date, priority (low, normal, high), task_template_id, notes_required, attachments_required (left out, an ordinary custom task starts from the setting of each employee's branch; an explicit value wins), and employee_id (yourself, or anyone in tasks.manage's scope) or assign_mode group with group_dimension and group_value; document_type_id, document_id, asset_type_id, asset_id and target_employee_id for their kinds. action status: fields.status todo, in_progress or done. A give_asset task, once completed, waits (status awaiting_confirmation) until the employee who got the asset runs action confirm_receipt. action complete (the assignee): fields completion_notes, asset_id (give asset), profile {column: value} (complete profile, a workflow task: the columns its profile_fields ask for); files go through the API or the screen. Workflow tasks (docs/boarding.md) in a sequential workflow wait for the earlier ones (locked). action delete: a pending task. action bulk_delete: fields.tasks (ids). action save_template / delete_template (tasks.templates.manage): with template_id, fields title {en, ar}, description, priority, due_in_days, related_to, branch_id (empty: the whole company), steps. steps on assign or a template: a list of {name {en, ar}, photos_allowed, videos_allowed, min_photos, min_videos, max_photos, max_videos}; a template with steps needs tasks.templates.use to assign, its own steps tasks.proof.require. group_dimension my_team: everyone who reports to you. action settings (tasks.proof.settings): the task settings, as GET/PATCH tasks/settings; without values read them, values may set task_default_notes_required, task_default_attachments_required and the task_proof_* switches, branch_id for one branch (null takes a key back to the company).

  Needs: self.tasks.update tasks.manage

  Parameters: company_id* action* task_id template_id fields values branch_id * = required

• manage_tv Changes data

  Office TV screens (tv.manage). action list: channels, TVs (no tokens) and items. save_channel (channel_id to change): fields name, layout (full, split, quad), areas (one list per area of: today, announcements, birthdays, off_today, coming_up, content (slides and videos), clock, attendance_qr (the TV site's rotating clock-in QR code)), is_default (TVs without a channel show it; one per company), active. delete_channel. save_device (device_id to change): fields name, branch_id, work_location_id (site), tv_channel_id, locale (en, ar, or empty: the link's ?lang); a new TV comes back with its link and token, shown once. rotate_device: a new link and token, once; the old one stops working. delete_device. save_item (item_id to change): fields kind (news, slide, video), title {en, ar}, body {en, ar}, starts_on, ends_on, active; pictures and video files (mp4/webm, within the upload_file_kb limit of company_limits) go through the API or the screen. delete_item.

  Needs: tv.manage

  Parameters: company_id* action* channel_id device_id item_id fields * = required

• mark_announcement_read Changes data

  Marks a company announcement read for you (your notification of it), as opening it on the screen does. Only one you may read; another is "not found". Returns how many notifications were marked.

  Needs: announcements.manage self.announcements

  Parameters: company_id* announcement_id* * = required

• task_proof Changes data

  Signed proof photos on tasks (docs/field-proof.md §23), the same as the tasks/{task}/proof API routes. action list (tasks.proof.view): the tasks with photos of the people in scope, with show (open, flagged, done, all), employee (id), q, page, per_page; each with its photos, videos, needs_look and last_photo_at. action show (tasks.proof.view): task_id, the task, its rules and photos, and can {void, request_upload, waive} for you. action own (self.tasks.view): task_id, one of your own tasks with every photo you took, open or finished. action void (tasks.proof.void): evidence_id, reason. action request_upload (tasks.proof.request_upload): task_id, note; at most once per task every 10 minutes. action waive (tasks.proof.waive): task_id, reason; the task no longer needs photos. action settings (tasks.proof.settings): with values task_proof_enabled, task_proof_offline_allowed, task_proof_departure, task_proof_min_progress_photos, and branch_id for one branch (null takes a key back to the company). Photos are only taken by the mobile app with its hardware key, never through MCP. To require proof on a new task pass fields.proof_required to manage_task action assign (tasks.proof.require).

  Needs: self.tasks.view

  Parameters: company_id* action* task_id evidence_id reason note values branch_id show employee q page per_page * = required

Work orders, sites, dispatch, signed field photos and overtime from field work.

Try asking: «Which jobs are open today?»

• field_dispatch Changes data

  The field dispatch board (docs/field-proof.md §12), as GET field/dispatch, GET field/jobs/{job}/candidates, POST field/jobs/{job}/reassign, POST field/jobs/bulk-cancel and GET field/jobs/{job}/events. action candidates (field.dispatch.manage): job_id, q; who could take the job, best first (available, matching zone or skill, nearest, fewest open jobs). action board (field.dispatch.view): the day's jobs (date Y-m-d, default today, plus open jobs from earlier days or without a date) with their sites and status, and the field employees with their latest verified photo position and, where the company uses live location and you have live_location.view, their live ping; filters branch_id, status, q. action reassign (field.dispatch.manage): job_id, employee_id (an active employee of the job's branch), note; an assigned or in-progress job goes to that employee alone, logged, and the employees are told. action bulk_cancel (field.jobs.cancel): job_ids (up to 200) and reason; open jobs are cancelled and logged, others come back as skipped (not_found, not_open). action events: job_id, the job's dispatch log.

  Needs: field.jobs.manage field.jobs.view live_location.view

  Parameters: company_id* action* date filters job_id employee_id note q job_ids reason branch * = required

• field_overtime Changes data

  Overtime from field proof (docs/field-proof.md §18), as the field/overtime API. action summary (field.overtime.view): job_id → the verified time on site against the schedule (before/after the shift, day off), the overtime, warnings and the linked request. action draft (field.jobs.overtime): job_id → draft the overtime request now for a submitted job. action mine (no permission): the signed-in employee's overtime requests from field jobs, drafts first. action submit: request_id, reason (required), overtime_type_id (optional) → the employee (or HR over them) sends the draft into the normal approval chain. action discard: request_id → cancel the draft. action queue (field.overtime.view): overtime from field jobs in your branches; filters status (pending by default, or all), q. action decide (field.overtime.approve): request_id, decision approved or rejected, note (required to reject); only when the request waits on you, as POST field/overtime/{id}/decide.

  Needs: field.jobs.manage self.field_overtime

  Parameters: company_id* action* job_id request_id reason overtime_type_id decision note filters branch * = required

• field_proof_settings Changes data

  The company's Field proof settings (field_setup.manage, docs/field-proof.md), as GET/PATCH field/settings. Without values: read them. values may set field_proof_enabled, field_offline_allowed, field_require_hardware_key, field_auto_overtime, field_job_stage_override, field_departure_photo (booleans); field_min_progress_photos, field_progress_interval_min, field_site_radius_m, field_max_accuracy_m, field_max_offline_hours, field_overtime_min_minutes (numbers); field_mock_policy, field_integrity_policy, field_outside_site_policy (reject or flag); field_recapture_policy (flag or off: the queued check for a photo of a screen or a print only ever flags). Everything starts off. With branch_id: that branch's own values over the company's, as GET/PATCH field/settings/branches/{branch}; each key comes back as {company, branch (null = inherited), effective, source}, and a value of null or "inherit" takes it back to the company's.

  Needs: field_setup.manage

  Parameters: company_id* branch_id values * = required

• geocode_address Changes data

  Street addresses from Mihnaro's own geocoder (docs/field-proof.md §21), as GET field/geocode/search and field/geocode/reverse. action search: q (2–200 characters, Arabic or English), lang (en or ar), optional lat and lng to prefer results near them, limit (1–10); returns places with label, area (street level, no house number), lat, lng and parts. action reverse: lat, lng, lang; returns the nearest address or null. available is false when the geocoder is down or off. Any user of a company with the FSM license; rate-limited per user.

  Needs: field.jobs.manage field.jobs.view field_setup.manage self.field_jobs

  Parameters: company_id* action* q lang lat lng limit * = required

• list_field_jobs Changes data

  Field work orders and sites (docs/field-proof.md), as GET field/jobs, field/sites and field/my-jobs. kind jobs (field.jobs.view or field.jobs.manage): filters status (assigned, in_progress, submitted, approved, rejected, cancelled), branch_id, site_id, employee_id, q, from, to, per_page; with job_id, one job with its photos. Filters also date (one day), flagged (jobs with a standing flagged photo) and flag (one code); each job has flagged_count. kind summary: the board's counts under the same filters (per status, today, in_progress, awaiting_review, flagged). kind flags: every flag and reason code with its plain-language label and explanation in English and Arabic (no permission needed). kind sites: the sites, q. kind mine: the signed-in employee's own jobs (no permission needed). Only the branches the role covers.

  Needs: field.jobs.manage field.jobs.view self.field_jobs

  Parameters: company_id* kind job_id filters branch * = required

• manage_field_customers Changes data

  FSM customers (docs/fsm-mobile.md), as GET/POST/PATCH/DELETE field/customers, with the same permissions. action list (filters: q, branch_id, active; field.customers.view), get (id), save (field.customers.create, or .edit with id; fields: name, contact_name, phone, email, address, notes, active, branch_id for a new one), delete (id; field.customers.delete; only a customer with no sites).

  Needs: employees.view_sensitive

  Parameters: company_id* action* id filters fields branch * = required

• manage_field_jobs Changes data

  Field work orders and sites (docs/field-proof.md, docs/fsm-mobile.md), as POST/PATCH/DELETE field/jobs and field/sites; each action its permission, all covered by field.jobs.manage: save_job field.jobs.create or .edit, decide field.jobs.review or .cancel, submit_without_departure field.jobs.review (job_id, fields.reason required: a job waiting for its departure photo goes to review without it, as POST field/jobs/{job}/submit-without-departure), delete_job field.jobs.delete (job_id; only an assigned one with no photos, parts or overtime), save_site field.sites.create or .edit (also field_customer_id), delete_site field.sites.delete (site_id; only with no work orders). action save_job: add a job, or change an assigned or in-progress one with job_id; fields title, description, branch_id (new only), field_site_id, priority (low, normal, high, urgent), planned_start_at, planned_end_at, estimated_minutes, assignee_ids (active employees of the job's branch), min_progress_photos and progress_interval_min (the job's own stage rules; only when field_job_stage_override is on, empty = the company's). action decide: job_id, fields.action approve or reject (a submitted job) or cancel (an open one), fields.note (required to reject or cancel). action save_site: add a site, or change one with site_id; fields name, address, latitude, longitude, radius_m (empty = company default), active, branch_id (new only).

  Needs: field.jobs.manage

  Parameters: company_id* action* job_id site_id fields branch * = required

• manage_inventory Changes data

  FSM inventory (docs/fsm-sections.md), as field/inventory/*, with the same permissions. Reading (field.inventory.view or .manage): list_parts (filters: q, category, low, active, branch_id, per_page), get_part (id), list_locations, get_location (id), list_movements (filters: part_id, location_id, job_id, type, from, to), job_parts (job_id). export_parts and export_movements (field.inventory.export; headers and rows). Parts: save_part (.create, or .edit with id; fields sku, name, category, unit, unit_cost, supplier, min_stock, notes, active, branch_id), delete_part (.delete). Locations (.locations): save_location (fields name, kind of warehouse, van, site, address, active, branch_id), delete_location. Stock on part id: receive (.receive; fields location_id, quantity, reference, note), adjust (.adjust; location_id, counted, note), transfer (.transfer; from_location_id, to_location_id, quantity, note), issue (.issue; location_id, job_id, quantity, employee_id, note), return (.issue; location_id, job_id, quantity, note).

  Needs: field.inventory.manage field.inventory.view

  Parameters: company_id* action* id job_id filters fields branch * = required

• manage_technicians Changes data

  FSM technicians (docs/fsm-sections.md), as GET/POST/PATCH/DELETE field/technicians, with the same permissions. action list (filters: q, availability, skill, zone, branch_id, per_page; field.technicians.view or .manage), get (id), export (field.technicians.export; returns headers and rows), save (field.technicians.create, or .edit with id; fields: employee_id for a new one, skills, zones, availability of available, busy, off_duty, on_leave, available_until, work_days with 0 = Sunday, day_start, day_end, max_daily_jobs, notes), delete (id; field.technicians.delete).

  Needs: field.technicians.manage field.technicians.view

  Parameters: company_id* action* id filters fields branch * = required

• manage_vehicles Changes data

  FSM vehicles (docs/fsm-sections.md), as field/vehicles/*, with the same permissions. Reading (field.vehicles.view or .manage): list (filters: q, status, driver_id, branch_id, per_page), get (id, with documents and logs), alerts (documents expiring and maintenance due), list_log (id, log of documents, maintenance, fuel). export (field.vehicles.export; headers and rows). save (.create, or .edit or .driver with id; fields plate_number, make, model, year, vin, status of active, maintenance, retired, driver_employee_id, odometer_km, notes, branch_id), delete (.delete). Log lines (field.vehicles.documents, .maintenance or .fuel): save_log (id is the vehicle, log, row_id to change one; documents: type, number, expires_on, note; maintenance: done_on, kind, description, vendor, cost, odometer_km, next_due_on; fuel: filled_on, liters, cost, odometer_km, station, employee_id), delete_log (id, log, row_id).

  Needs: field.vehicles.manage field.vehicles.view

  Parameters: company_id* action* id row_id log filters fields branch * = required

• request_field_upload Changes data

  Asks the employees on an open field job to upload the signed photos still saved on their phones (field.jobs.request_upload in the job's branch, docs/field-proof.md §12), as POST field/jobs/{job}/request-upload. Fields: job_id, note (optional, up to 500 characters). They get a notice and a push; the phone sends its drafts by itself once it is online and the app can run. At most once per job every 10 minutes. It can't read the phone: the answer says who was told, not how many photos wait.

  Needs: employees.view_sensitive

  Parameters: company_id* job_id* note branch * = required

• review_field_evidence Changes data

  Signed field photos (field.evidence.review, docs/field-proof.md), as GET field/evidence and POST field/evidence/{id}/void. action list: filters job_id, stage (arrival, progress, completion, departure), employee_id, accepted, flag (e.g. mock_location, outside_site, time_unverified), flagged (any flag, not voided: the review queue), voided, branch_id, from, to, per_page. action show: evidence_id, every detail (time, place, flags, device key, hash) and its void log. action void (field.evidence.void): evidence_id and reason (required); the photo stays, the void is logged, and the job goes back to the stage its standing photos show. action c2pa: evidence_id, its C2PA (Content Credentials) copy signed by the Mihnaro server: status (none, pending, signed, failed), validation, trust (self_signed = Mihnaro's own certificate, validators show an unknown signer), assertions, as GET field/evidence/{id}/c2pa. action c2pa_download: evidence_id, the signed copy as base64 (filename, mime, size, sha256), only when signed, valid and not voided, as GET field/evidence/{id}/c2pa/download. action devices (field.evidence.devices): the phone keys in the branches covered; action revoke_key (field.evidence.devices): key_id (a lost phone). Photos themselves are only taken by the mobile app with its hardware key, never through MCP.

  Needs: field.evidence.review

  Parameters: company_id* action* evidence_id reason key_id filters branch * = required

Fingerprint and door devices, who is on them, biometric templates and door access.

Try asking: «Which devices are offline?»

• access_control Changes data

  Door access control like BioTime (devices.manage, docs/devices.md). kind time_zones (name {en, ar}, device_tz_id 2-50, schedule {sun..sat, holiday: up to 3 [["08:00","12:00"]] intervals}), levels (name, access_time_zone_id, doors [{device_id, door (0 = all)}]) or assignments (access_level_id, target_type employee|group|department|branch|position|all|visitor, target_id (a group: whoever joins it gets the access, whoever leaves loses it; or target_ids [..] for several employees at once: one assignment each), effect allow|deny, biometric_device_id for a device-only deny, visitor_name, visitor_pin, visitor_card, starts_at, ends_at, note). action list, save (id to change; fields), delete (id). Every change syncs the devices.

  Needs: devices.manage

  Parameters: company_id* kind* action* id fields * = required

• biometric_templates Reads only

  Biometric templates and compatibility (devices.manage, docs/devices.md). view templates: an employee's templates (type, algorithm version, source device); the template data only with include_data true and employees.view_sensitive, and the export is audited. view compatibility: every template against every device (or device_id) with the reason a device can't take one. view conflicts: slots two devices hold different data for, each version with its device, enrolment and seen time (settle with resolve_template_conflict). view duplicates: the same template data under different PINs (possible duplicate person).

  Needs: devices.manage employees.view_sensitive

  Parameters: company_id* view employee_id device_id include_data * = required

• device_action Changes data

  Act on a device (devices.manage, docs/devices.md). action sync (send what differs), pull (all users and templates back from the device), pull_logs (the attendance log from the day from (Y-m-d) to the day to, default today; punches already received are not doubled), info, check, reboot, clear_log, open_door / close_door (door, seconds), set_time; queued for the device's next poll. action remove_users (pins): take people who left or numbers no employee owns off this device; current employees are refused. action settings: access_mode attendance (everyone enrolled; punches count) | access (door only: people with an access level, time zones enforced; punches not counted as attendance) | both (door rules and punches count), sync_enabled, strict_users, family terminal|panel, lock_count, and the branches it serves: all_branches true, or branch_ids (a device shared between branches); its punch rules (docs/devices.md, "Punch rules"): punch_mode first_last|all|function (null = the sheet template's), pair_breaks (with first_last: the punches between the first and the last pair up as breaks), break_function_id (breaks kept as records of that attendance function; none = break time is not worked), debounce_minutes (double-tap window, null = the company's), punch_in_window_minutes and punch_out_grace_minutes (punches by shift, docs/attendance.md: a shift's own windows come first, null = the company's); with recompute_from (Y-m-d) the device's punches since then are paired again under the rule; its network lock (docs/attendance-security.md): allowed_ips (addresses or CIDR ranges, comma-separated; requests from elsewhere are refused; empty = anywhere) and confirm_ip true (trust the address it reports from now, after an "address changed" alarm). action recompute with from (Y-m-d): pair the device's punches since then again. action retry or cancel with command_id.

  Needs: devices.manage

  Parameters: company_id* action* device_id command_id pins door seconds from to access_mode sync_enabled strict_users family lock_count all_branches branch_ids punch_mode pair_breaks break_function_id debounce_minutes punch_in_window_minutes punch_out_grace_minutes recompute_from allowed_ips confirm_ip * = required

• door_events Changes data

  Door events the devices reported (devices.manage, docs/devices.md): granted, denied (with the reason), alarm (forced door, duress, tamper) and state. action list with optional device, result, employee, pin, door, from, to, alerts (unacknowledged alerts only); up to 500, newest first. action acknowledge with event_id.

  Needs: devices.manage

  Parameters: company_id* action event_id device result employee pin door from to alerts * = required

• list_devices Reads only

  Fingerprint and access devices (devices.manage, docs/devices.md). view list (default): every device with online status, last seen, IP, family, model, firmware. With device_id: view detail (capabilities and counts on the device vs Mihnaro), commands (command history, optional status), users (the device's users against Mihnaro's: in_sync, changed, missing, extra), plan (what a sync would send) or audit (the device audit log; device_id optional). view sync_report: people whose devices are not all in sync (user record, slots missing, outdated, in conflict, pending, out of capacity).

  Needs: devices.manage

  Parameters: company_id* view device_id status * = required

• list_pending_biometrics Reads only

  New biometrics waiting for HR (devices.manage, docs/devices.md): a new finger, face or palm, or a newer enrolment of one, reported by a device; and conflicts (two devices hold different data for a slot). Each item: employee, slot, source device, kind new|conflict, the devices a publish would reach (targets) and those that can't take it with the reason (incompatible). Optional employee_id. Decide with publish_biometrics.

  Needs: devices.manage

  Parameters: company_id* employee_id * = required

• manage_device_people Changes data

  People on devices (devices.manage, docs/devices.md); the PIN on devices is the employee's biometric ID. action list: active people (q by number, biometric ID or name; department; page) with their profile, enrolled device ids and template count. action get: an employee's device profile, enrolments, why they are (not) on each device and template list. action enroll: by employees (individual enrolments) or by department|branch|position|group|all with ids, onto device_ids: an enrolment rule worked out at every sync, so people who join later are added and people who leave are taken off. action rules (device_id): the device's rules and its individually enrolled employee ids. action exclude: ids (employees) kept off device_ids whatever rule would add them. action delete_rule (rule_id). action unenroll: employee_id (or group_id) from device_ids. action profile: employee_id with card, password (digits), privilege (0 user, 2 enroller, 6 admin, 14 super admin), verify_mode (default, finger, face, card, password, card_and_finger, face_and_password...), enabled, push_photo. action remove: off every device now. action pull_templates: ask the devices for the person's templates again.

  Needs: devices.manage

  Parameters: company_id* action* device_id rule_id q department page employee_id group_id by ids device_ids card password privilege verify_mode enabled push_photo * = required

• publish_biometrics Changes data

  Publish biometrics to devices (devices.manage, docs/devices.md). action decide: template_id with decision publish (device_ids to publish only there), source_only or reject. action publish_all_pending: every pending item (optional employee_id, or employee_ids for several people). action auto_publish: read the setting, or set it with on true|false (new biometrics then reach the person's other devices without approval). action publish_slot: template_id to device_id (or every device). action publish_missing: employee_id's approved slots to every device they may use. action remove_slot: template_id off device_id, or out of the master set without device_id; needs confirm true. action update_all: send every approved template, photo and user record again to all devices (optional employee_id); returns a batch. action progress: batch → queued/sent/done/failed per device. action matrix: employee_id's slots × devices.

  Needs: devices.manage devices.templates.withdraw

  Parameters: company_id* action* template_id employee_id device_id device_ids employee_ids on decision confirm batch * = required

• resolve_template_conflict Changes data

  Settle a template conflict (devices.manage, docs/devices.md): template_id with version_id keeps that version and pushes it to every device the person may use; or re_enroll_device_id asks that terminal to enrol the slot again (the newer enrolment then wins). Logged in the device audit log.

  Needs: devices.manage

  Parameters: company_id* template_id* version_id re_enroll_device_id * = required

Groups of employees used on devices and shared shifts.

Try asking: «List the employee groups»

• employee_groups Changes data

  Employee groups like BioTime (employee_groups.manage or devices.manage, docs/employee-groups.md). action list; get (id): members with how they are in (member = picked, rule = by department/position/branch); save (id to change; fields name {en, ar}, description {en, ar}, color #rrggbb, branch_id (empty = every branch), rules {departments, positions, branches: [ids]}, member_ids); delete (id: its door access and shift shares go too); add_members / remove_members (id, employee_ids). Put a group on devices with manage_device_people enroll by group, and give it door access with access_control assignments target_type group: joining or leaving the group then follows on the devices.

  Needs: devices.manage employee_groups.manage

  Parameters: company_id* action* id fields employee_ids * = required

Two-step verification, password rules, single sign-on and its audit log, and how long logs are kept.

Try asking: «Does my company require two-step verification?»

• get_log_retention Reads only

  How long the company keeps its activity log (retention 6 | 12 | 24 | forever), the choices allowed under Mihnaro's maximum, the months actually kept and the date before which entries are deleted tonight.

  Needs: settings.manage

  Parameters: company_id* * = required

• get_my_two_factor Reads only

  My two-step verification: whether it is available, on, required (by the platform or one of my companies), and how many recovery codes are left. Setting it up or turning it off is done in the app or the API, never here, so keys and codes don't pass through an AI tool.

  Needs: No single permission: it follows your role and branches

• get_sign_in_settings Reads only

  System preferences → Sign-in security: whether the company requires two-step verification (and the platform mode: off, optional, required), its own password policy next to Mihnaro's, and its single sign-on: OpenID Connect or SAML 2.0 provider, "SSO only" and the exempt users, and the URLs to give the provider (SAML ACS, entity ID, metadata). The client secret is never returned, only whether it is set.

  Needs: settings.manage

  Parameters: company_id* * = required

• get_sso_audit_log Reads only

  The company's single sign-on audit log, newest first: sign-ins through the provider (OpenID Connect or SAML), refusals with the reason, password sign-ins blocked by "SSO only", and changes to the sign-in settings (field names only).

  Needs: settings.manage

  Parameters: company_id* limit event * = required

• list_legal_rules Reads only

  Payroll legal validation (HR module): the payroll rules not confirmed under Iraqi law. "blocked" rules stay off until validated; "unverified" ones work but are flagged. Each shows whether it is validated, by whom, the reference and when.

  Needs: legal_rules.validate payroll_setup.manage

  Parameters: company_id* * = required

• reset_user_two_factor Can delete

  User setup: turn off a user's two-step verification (lost phone) so they set it up again. Not for yourself, the company admin, or someone who also works in another company (Mihnaro support does those).

  Needs: users.manage

  Parameters: company_id* user_id* * = required

• set_legal_validation Changes data

  Needs legal_rules.validate (the company admin always has it): record that a payroll rule was legally validated (who validated it and the reference, e.g. a lawyer's opinion), or withdraw the validation. A blocked rule starts working once validated.

  Needs: legal_rules.validate

  Parameters: company_id* rule* action* validated_by reference * = required

• update_log_retention Changes data

  Set how long the company keeps its activity log: 6, 12 or 24 months, or forever (only the choices under Mihnaro's maximum). Older entries are deleted by the nightly cleanup, which logs itself. Shorter retention deletes history for good: confirm with the user first.

  Needs: settings.manage

  Parameters: company_id* retention* * = required

• update_sign_in_settings Changes data

  Change the company's sign-in security. Send only what changes. Two-step verification; the company's own password policy (pw_*: it only tightens Mihnaro's); single sign-on on or off, its protocol (oidc or saml), OpenID Connect issuer URL and client ID, SAML provider entity ID, sign-in URL and email attribute; "SSO only" (no password sign-in except for the exempt users; turning it on exempts you) and the exempt user ids. The OIDC client secret and the SAML certificate or metadata can't be set here on purpose: enter them on the screen or through the API.

  Needs: settings.manage

  Parameters: company_id* two_factor_required sso_enabled sso_name sso_issuer sso_client_id sso_protocol sso_only sso_exempt_user_ids saml_idp_entity_id saml_idp_sso_url saml_email_attribute pw_min_length pw_upper pw_lower pw_numbers pw_special pw_max_age_days pw_reuse pw_max_attempts pw_lock_minutes * = required

Your notifications, API keys and webhooks, connected systems, the activity log, phones using the app, mass actions and your own dashboards.

Try asking: «Show my unread notifications» «Who changed this record?»

• app_reminders Changes data

  People not on the Mihnaro app yet (docs/platform-control.md «لم يدخلوا التطبيق بعد»): current employees in your scope who never signed in to the app. action list (app_devices.view; filters q, branch_id, account yes|no; page, per_page): employee_id, number, name, branch, has_account, email and mobile half hidden, last_reminded_at, reminders. action send (app_devices.remind): channel email|whatsapp, employee_ids [..] or all=true (with filters), at most 500, nobody twice in 24 hours, a few a minute: someone with an account gets the store links and the sign-in steps, someone without one the invitation to choose a password; push can't reach them. Returns queued, invitations, skipped {reason: count}. Every send is in the notifications log.

  Needs: app_devices.remind app_devices.view

  Parameters: company_id* action* channel employee_ids all filters page per_page * = required

• export_notification_log Reads only

  The notifications log as a file (notifications.log.view, docs/notifications.md "سجل الإشعارات"), as GET notification-log/export: format csv (default) or xlsx, with the same filters as list_notification_log (at most 10,000 notices), or with send (an id) that notice's recipients and each channel's answer. Returns filename, mime, size and the file as base64.

  Needs: notifications.log.view notifications.manage

  Parameters: company_id* format send from to category channel status person branch kind actor q * = required

• get_activity_log Reads only

  The company's activity log (activity.view, docs/activity-log.md), newest first, 40 a page. tab changes: record changes with old → new values (filters scope employee/time/payroll/organization/company/system, area, action created/updated/deleted, level user/employee/branch/company, user, employee, branch, from, to); secrets and ID numbers show as •••. tab requests: every change request from the screens, the API and MCP (filters user, channel web/api/mcp, from, to, q). tab sign_ins: the company's people's sign-ins (filters user, from, to, new_only).

  Needs: activity.view

  Parameters: company_id* tab scope area action level user employee branch channel from to q new_only page * = required

• get_help Reads only

  The help center (docs/help.md): where things are and how the common tasks are done, as topics with their steps and the page to open, only for what the user may use, in their language.

  Needs: employees.view_sensitive

  Parameters: company_id* * = required

• get_person_app_devices Reads only

  A person's phones with the Mihnaro app and their sign-in activity in this company (docs/platform-control.md "Phone activity"): each phone (version, state, push, first and last IP with the approximate local GeoIP place, first and last seen) with its latest 30 events, and other_activity not tied to a known phone. user_id defaults to the signed-in person (anyone may see their own); another person needs app_devices.view with a scope that covers them. Plus map_points, the events map (docs/platform-control.md «خريطة الأحداث»): [{type clock_in|clock_out|field_photo|sign_in|sign_in_failed|sign_out|app_open|other, event, at, lat, lng, approximate (true = a city from the local GeoIP for the event's IP), accuracy, place, event_id (its timeline row), install_id}], newest first; GPS points (punches, Field proof photos) only with the location permission (map_gps). Event GPS (docs/platform-control.md «موقع الأحداث»): every event row has has_gps (whether the app sent its own GPS point with it: sign_in, app_open, version_changed); with the location permission (platform.phones.location, or live_location.view in scope) the row also carries location {lat, lng, accuracy, at, source app_event, mocked}. Without it only the IP place shows, which is approximate (a city). map_points now also include live-location pings (type live) and the app's own GPS with events; each point has source punch|live|field|app_event|ip (ip = approximate, from the IP); map_gps_hidden = GPS points exist that this viewer may not see.

  Needs: app_devices.view live_location.view platform.phones.location

  Parameters: company_id* user_id * = required

• get_person_device_context Reads only

  The phone details the Mihnaro app sent for a person in this company (app_devices.context, docs/platform-control.md «بيانات الهاتف»), collected only for the categories the company's switches allow: phones [{install_id, device_id, model, platform, location_state {location always|while_using|denied|undetermined, precise, services}, latest {device, network, battery, permissions, security (with the last punch's app integrity verdict), time (with clock_offset_ms vs the server), locale, health}}] and history [{at, trigger open|resume|sign_in|punch, category, install_id, event_id, data}], newest first. Filters: install_id, category, limit (≤500). Same API: GET /api/v1/app/companies/{id}/app-devices/people/{user}/context. Never contains contacts, media, messages, other apps, hardware ids or advertising ids.

  Needs: app_devices.context

  Parameters: company_id* user_id* install_id category limit * = required

• list_accounting Reads only

  Direct accounting connectors (each ledger needs integrations.{provider}.manage, which integrations.manage grants; docs/accounting-connectors.md): odoo, quickbooks, xero, netsuite, business_central, sap_b1, sap_s4hana, dynamics_fo. kind providers: every ledger and whether the company is connected. kind connection (provider): its state, non-secret fields, posting options and catalog counts (secrets are never returned, only whether each is saved). kind catalog (provider): the ledger's accounts, analytic accounts, partners and journals as last read. kind mappings (provider): Mihnaro accounts, cost centers, branches and employees with their ledger ids and suggestions. kind preview (provider, run_id): the payroll's journal entries in ledger ids, with references and anything blocking them. kind postings (provider optional, status, run_id): the posting log. kind posting (posting_id): one posting with its lines and attempts.

  Needs: integrations.manage

  Parameters: company_id* kind* provider branch_id run_id posting_id status * = required

• list_app_device_activity Reads only

  The sign-in activity of the company's people on the Mihnaro app (app_devices.view, docs/platform-control.md "Phone activity"), only for the people the permission's scope covers and without what other companies recorded: sign-ins and failed attempts, sign-outs, app opens and version changes, push registrations and answers, phone approvals and blocks, each with time, IP and approximate place (local GeoIP), app version, system and model. Filters: user_id, install_id (a phone from list_app_devices), device_id, event, result, from, to; page, per_page. Event GPS (docs/platform-control.md «موقع الأحداث»): every event row has has_gps (whether the app sent its own GPS point with it: sign_in, app_open, version_changed); with the location permission (platform.phones.location, or live_location.view in scope) the row also carries location {lat, lng, accuracy, at, source app_event, mocked}. Without it only the IP place shows, which is approximate (a city).

  Needs: app_devices.view live_location.view platform.phones.location

  Parameters: company_id* user_id install_id device_id event result from to page per_page * = required

• list_app_devices Reads only

  The phones the company's people use the Mihnaro app on (app_devices.view, docs/platform-control.md "The company's view"), only for the people the permission's scope covers (company-wide or some branches): person, branches, platform, system version, model, app version, state (below_min, outdated, latest, newer = a test build above the store's latest, store_unknown, unknown = an old app before 1.1 that never reported its version), the last GPS location (only for people whose location the caller may see with live_location.view), push status and first/last seen, plus the summary per platform. Filters: q, branch_id, platform, version, state, push, signed_in, seen_days, shared (only phones used by more than one account; each row has shared {accounts, others, list} when it is); page, per_page.

  Needs: app_devices.view live_location.view

  Parameters: company_id* q branch_id platform version state push signed_in shared seen_days page per_page * = required

• list_connected_accounts Reads only

  The company's connected accounts (docs/integration-connections.md): Zoom, Google, Microsoft, LinkedIn (needs integrations.connections.manage) and each accounting ledger (needs integrations.{provider}.manage); integrations.manage grants all. Per provider: mode (company = one account for every branch, branch = each branch may have its own, the company's is the fallback), the redirect URI and scopes to register at the provider, the company's connection, and each branch's with "uses" (branch, company or none). Client secrets and tokens are never returned, only has_client_secret.

  Needs: integrations.manage

  Parameters: company_id* * = required

• list_integrations Reads only

  API keys and webhooks (integrations.api_keys.manage; kind marketplace needs any integration permission; integrations.manage grants all; docs/integrations.md). kind keys: the API keys (prefix, abilities, IPs, who they act as, status; never the key). kind webhooks: URLs, events and last delivery (never the secret). kind deliveries: the delivery log, optionally for webhook_id and status delivered or failed. kind delivery: one delivery with its body and every attempt (delivery_id). kind events: the events a webhook can listen to. kind marketplace: the connector catalogue by category with each one's state (filters category, active active|inactive, q).

  Needs: integrations.manage

  Parameters: company_id* kind category active q webhook_id delivery_id status * = required

• list_my_notifications Reads only

  The person's own notices in the company (the header bell, docs/notifications.md), newest first, with the unread count; after_id gives only the ones that arrived since (the live bell). unread true for unread only; category one of requests, payroll, attendance, performance, tasks, recruitment, documents, announcements, people, greetings, security, general; page (25 a page).

  Needs: employees.view_sensitive

  Parameters: company_id* unread category page after_id * = required

• list_notification_events Reads only

  Which events notify whom (notifications.manage, docs/notifications.md §13): every event with its recipients (en, ar), category, link, channels, kind (request, record, setup, security, action, scheduled) and whether the company has its category on. Filters: kind, category, q (words).

  Needs: notifications.manage

  Parameters: company_id* kind category q * = required

• list_notification_log Reads only

  The company's notifications log (notifications.log.view, docs/notifications.md "سجل الإشعارات"), as GET notification-log: every notice sent, newest first, with category, event (the code that sent it), text en/ar, link, related record, triggered_by (null = the system), recipients, bell read counts and per channel (push, email, whatsapp) how many people got each status (accepted, sent, logged = written to the log only and NOT delivered, queued, held, skipped, no_device, failed). Only the people in your scope are counted; categories whose records you can't open are left out. Filters: from, to (dates), category, channel (bell, push, email, whatsapp), status (delivered, failed, logged, queued, held, skipped, no_device, read, unread), person (user id), branch (id), kind (system, person, announcement), actor (user id), q (words). Also returns summary (sent today, failed, delivery rate per channel) and channels (whether email, push and WhatsApp can deliver right now).

  Needs: notifications.log.view

  Parameters: company_id* from to category channel status person branch kind actor q page limit * = required

• list_shared_phones Reads only

  Phones used by more than one account (app_devices.view, docs/platform-control.md «الهاتف المشترك»), for the people the permission's scope covers: each phone row as list_app_devices plus shared {accounts (how many accounts used this phone, any company), others (how many of them you can't see: other companies or outside your scope, never named), list [{user, order (1 = first on the phone), first_used_at, last_used_at, first_sign_in_at, last_sign_in_at, sign_ins, allowed (an HR exception), this_phone_row}]}, the summary, and the company's policy {mode allow|warn|block, max_accounts, inherit (the Mihnaro default)}. Filters as list_app_devices; page, per_page.

  Needs: app_devices.view

  Parameters: company_id* q branch_id platform signed_in seen_days page per_page * = required

• manage_accounting Can delete

  Direct accounting connectors (each ledger needs integrations.{provider}.manage, which integrations.manage grants; docs/accounting-connectors.md). provider: odoo, quickbooks, xero, netsuite, business_central, sap_b1, sap_s4hana or dynamics_fo. action save: fields = the provider's connection fields (see list_accounting kind connection; secrets are stored encrypted, empty keeps the saved one) and posting options post_on_approval, post_off_cycle, kinds (payroll, contributions, cost_center, bank_transfer), post_state posted|draft, entry_date month_end|approval, journal, rounding_account, currency, send_partners. action oauth_url: the consent link for QuickBooks and Xero (open it signed in to Mihnaro). action test: sign in and read the organization. action refresh: read the ledger's accounts, analytics, partners and journals. action disconnect: forget the credentials. action map: items [{type account|cost_center|branch|employee, local_key, external_id (empty removes)}]. action auto_match: map accounts whose codes match. action post: run_id, post an approved payroll (idempotent: what is posted is never sent twice). action retry / reverse / repost: posting_id. action sync_employees: employee_ids optional.

  Needs: integrations.manage

  Parameters: company_id* action* provider branch_id fields items run_id posting_id employee_ids * = required

• manage_api_key Can delete

  Company API keys (integrations.api_keys.manage, which integrations.manage grants; docs/integrations.md). action create: fields name, abilities (read, write, update, delete), ip_addresses (list; empty = any), expires_on, user_id (who it acts as; default the caller), auth_type (basic, oauth1, oauth2, credentials) with its outgoing credentials. The key is in the answer ONCE as token: hand it over safely, it can't be shown again. action update: api_key_id and the same fields (a blank secret keeps the saved one). action revoke: api_key_id; anything using it stops at once.

  Needs: integrations.manage

  Parameters: company_id* action* api_key_id fields * = required

• manage_connected_account Changes data

  Manages one of the company's connected accounts (docs/integration-connections.md), the same operations as the screen and the API. action mode (provider, mode company|branch; also for the ledgers): one account for the whole company or one per branch. action save (provider, branch_id, app own|platform, client_id, client_secret write-only, tenant for microsoft, organization = LinkedIn page id). action authorize_url (provider, branch_id): the consent page to open in a browser signed in to Mihnaro as the same person. action test (provider, branch_id): reads the signed-in account. action disconnect (provider, branch_id): revokes and clears the tokens. branch_id empty = the whole company's connection. Providers zoom, google, microsoft, linkedin (ledgers are set up with manage_accounting and its branch_id).

  Needs: integrations.manage

  Parameters: company_id* action* provider* branch_id mode app client_id client_secret tenant organization * = required

• manage_my_dashboards Changes data

  The person's own dashboards (docs/dashboards.md): tabs of widgets on top of the fixed dashboards, each showing one figure the person may see. action metrics: what can be added. action list: their dashboards (the first time, ZenHR's "Default Dashboard" is made for them with its stock widgets they may see; is_default marks it). action show: dashboard_id with every widget's figure. action create: name {en, ar}. action rename: dashboard_id, name. action delete: dashboard_id. action add_widget: dashboard_id, metric, title {en, ar}, chart, width 1–4 (quarters). action update_widget: widget_id with title, chart, width. action remove_widget: widget_id. action reorder: dashboard_id, ids (widget ids in order). action set_interval: dashboard_id, interval (1–6 for every widget whose report offers it, 0 for each widget's own). action order_dashboards: ids (the person's dashboard ids in order). action home_widgets: the HR dashboard Home Page widgets the person may see (the widget registry, config/dashboard-widgets.php), in their order, with width, shown and the permission each needs; a widget without its permission is never listed. action save_home_widgets: order [keys], show [keys] (the rest hidden) and widths {key: 1–4}, each optional. action home_sections / save_home_sections (show [keys]): the older form, which widgets show. A Command Center report widget (Mawarid's ZenHR Command Center, employees.view): metric report with report_type (approved_leaves, approved_vacations, contract_expiry, document_expiry, termination_reasons, end_of_probation, headcount, joiners_leavers, overtime_hours, pending_tasks, retention_rate, turnover), breakdown for headcount (age_group, gender, nationality, service_period, work_type), level (company, branch, work_location, department, section, group, project, job_role) with unit_ids, interval (1 Today, 2 7D, 3 30D, 4 3M, 5 6M, 6 12M, as the report offers), upcoming, options (the report's extra field, e.g. leave_type_id, document_type_id, termination_category, overtime_type, task_kind; company_documents for document_expiry) and chart (numbers, stacked, bar, line, area, donut, pie, as the shape allows).

  Needs: employees.view self.dashboard

  Parameters: company_id* action* dashboard_id widget_id name metric title chart width ids report_type breakdown level unit_ids interval upcoming options show order widths * = required

• manage_my_notifications Changes data

  The person's own notices and channels (docs/notifications.md). action read: mark notice_id read (unread true to mark it unread). action read_all: mark every notice read. action preferences: their channels per category (in_app, email, whatsapp). action save_preferences: categories {category: {in_app, email, whatsapp}}; sign-in alerts always stay in the bell, and WhatsApp needs a mobile number on the profile.

  Needs: employees.view_sensitive

  Parameters: company_id* action* notice_id unread categories * = required

• manage_notification_setup Changes data

  The company's Notifications setup (notifications.manage, docs/notifications.md). Without save: categories_off, receiver_emails, the reminders and document_notice (each expiring document type with its notify_before period). save true with any of: categories_off (list of categories no one is told about; security can't be off), receiver_emails (list, copies of employee-record reminders), reminders {key: value}: switches rem_contract_on, rem_probation_on, rem_documents, rem_anniversary, rem_anniversary_employee, rem_birthday, rem_birthday_greetings, punch_alerts_on (true/false); days rem_contract_hr_days, rem_contract_manager_days, rem_contract_employee_days, rem_probation_hr_days, rem_probation_manager_days, rem_probation_employee_days, rem_documents_hr_days, rem_documents_manager_days, rem_documents_employee_days, rem_anniversary_hr_days, rem_anniversary_manager_days, rem_birthday_hr_days (0–365, null = not told); minutes punch_alert_employee, punch_alert_manager, punch_alert_hr (0–2880).

  Needs: notifications.manage

  Parameters: company_id* save categories_off receiver_emails reminders document_notice email_everyone * = required

• manage_slack Changes data

  The company's Slack channel (integrations.slack.manage, which integrations.manage grants; docs/integrations.md): a readable line is posted there for the webhook events chosen. action show: connected or not, and the events (the webhook address is a secret and is never returned). action save: fields webhook_url (a Slack incoming webhook, https://hooks.slack.com/…; empty keeps the current one), events (see list_integrations kind events), disconnect, test (post a test line now; the answer has Slack's test_status).

  Needs: integrations.manage

  Parameters: company_id* action* fields * = required

• manage_webhook Can delete

  Company webhooks (integrations.api_keys.manage, which integrations.manage grants; docs/integrations.md). action create: fields url (public http/https), events (see list_integrations kind events), name, format json or xml, active, group (financial_employee or financial_journal for a financial integration), api_key_id (signs the call with that key's authentication). The signing secret is in the answer ONCE as secret. action update: webhook_id and the fields to change. action delete: webhook_id (its log goes too). action rotate_secret: a new secret, returned once. action test: send a test event now and return the delivery. action resend: delivery_id, send a failed delivery again now.

  Needs: integrations.manage

  Parameters: company_id* action* webhook_id delivery_id fields * = required

• run_mass_action Can delete

  One change for many employees (docs/activity-log.md "Mass actions"), through the same rules as changing one. Always run with dry_run true first and show the person the lines. tab personal (employees.manage): gender, marital_status, religion, nationality (2 letters) with nationality_action empty (set it), add (as the second) or replace (with nationality_to_replace), citizen (citizen/non_citizen), roster_action add/remove with roster_shift_id, roster_from, roster_to and roster_conflict keep|replace (needs attendance.manage). tab professional (employees.manage): position_id, department_id and the other org unit ids, manager_id, supervisor_id, work_type, employee_kind, shift_id (default shift, at once), effective_date (required; dated professional data). tab financial (payroll.manage): one of basic_salary, raise_amount, raise_percent; salary_count, company_bank_account_id, payment_method, social_security_rule_id, effective_date (required; a new salary package), reason. employee_ids: every one must be in scope. kind history lists past mass actions.

  Needs: attendance.manage employees.manage payroll.manage

  Parameters: company_id* kind tab changes employee_ids dry_run * = required

• send_phone_test_push Changes data

  One test notification to one phone of a person in your scope (docs/notifications.md «الإشعار التجريبي»): install_id from list_app_devices. Straight to Apple or Google, nothing in the bell, logged on the phone's timeline (push_test) with who sent it. Returns sent and, per token: provider, status (ok, invalid, error), error, environment (which of Apple's servers took it), fallback (the first server refused it) and reason in plain words. "ok" means accepted for delivery, not shown on screen. At most 5 a minute per phone. Needs app_devices.test_push.

  Needs: app_devices.test_push

  Parameters: company_id* install_id* * = required

• shared_phone_allowances Changes data

  HR exceptions to one account per phone (docs/platform-control.md «الاستثناء»): let one more account use a phone another account already uses (a shared tablet at reception). action list (app_devices.view; phone_key optional, active_only): the exceptions for the people in scope. action allow (app_devices.allow_shared): user_id, install_id (a phone row from list_shared_phones or list_app_devices) or phone_key, reason (3–500 chars); logged on the phone's timeline and told to the person. action revoke (app_devices.allow_shared): allowance_id. Same as /api/v1/app/companies/{id}/app-devices/allowances.

  Needs: app_devices.allow_shared app_devices.view

  Parameters: company_id* action* user_id install_id phone_key reason allowance_id active_only * = required

• show_notification_log Reads only

  One notice of the notifications log in full (notifications.log.view, docs/notifications.md "سجل الإشعارات"), as GET notification-log/{id}: the send, then every person in your scope with their branch, bell (read and when), push (status and what Google/Apple answered per phone), email (status, reason, and the mail log row: via, attempts, error) and WhatsApp; receiver emails too when you see the whole company.

  Needs: notifications.log.view

  Parameters: company_id* id* * = required

Finding anything in the company by name.

Try asking: «Find everything about Ali Hassan»

• global_search Reads only

  Search the company system the way the top bar does (Ctrl+K): employees (by name in Arabic or Latin letters, number, phone), requests and time off (by number such as LV-000012), documents, contracts, payslips, payroll runs, tasks, letters, assets, announcements, departments, job titles, pages, settings and shortcuts such as "Add employee". Typos and partial words are fine. It understands plain Arabic or English filters, e.g. "طلبات إجازة معلقة بفرع Ltd", "موظفين قسم الحسابات", "عقود تنتهي هذا الشهر", "pending overtime requests", "رواتب أكتوبر", and says what it understood. Only what the user may see, in the current branch workspace (or the branch argument). Results come in groups, each with a title, subtitle, url and target (what it opens in the mobile app, or null). A field hidden from the user is neither searched nor shown.

  Needs: employees.view_sensitive

  Parameters: company_id* q groups limit without filters branch * = required

Layout and colors, for you and for the company.

Try asking: «Switch me to dark mode»

• get_app_colors Reads only

  The mobile app colors of a company or one of its branches (app_colors.view): what this level saved, what people see (with the darker button color when white text is hard to read on the chosen one), what it follows, and which branches have their own. Same as GET /api/v1/app/companies/{company}/settings/app-colors.

  Needs: employees.view_sensitive

  Parameters: company_id* branch_id * = required

• get_appearance Reads only

  The look in a company: the company's saved choices (for settings.manage), whether people may choose their own, the signed-in person's own choices and what they see, and every allowed value. Same as GET /api/v1/app/me/appearance and .../settings/appearance.

  Needs: settings.manage

  Parameters: company_id* * = required

• update_app_colors Changes data

  Changes the mobile app colors of a company or one of its branches (app_colors.manage): primary (buttons, active tabs, links), secondary (header, titles), as #RRGGBB. Only what is given changes; empty follows the level above; reset=true clears both. The admins are told. Same as PATCH and DELETE /api/v1/app/companies/{company}/settings/app-colors.

  Needs: employees.view_sensitive

  Parameters: company_id* branch_id primary secondary reset * = required

• update_company_appearance Changes data

  System preferences → Appearance (settings.manage): the company's default look for everyone, and allow_user_override (may people choose their own). Only the options given change; empty follows the platform. Same as PATCH /api/v1/app/companies/{company}/settings/appearance.

  Needs: settings.manage

  Parameters: company_id* allow_user_override mode layout color sidebar topbar topbarcolor card size width loader * = required

• update_my_appearance Changes data

  The signed-in person's own layout, colors and mode, when their company lets people choose. Only the options given change; empty follows the company. Same as PATCH /api/v1/app/me/appearance.

  Needs: employees.view_sensitive

  Parameters: company_id* mode layout color sidebar topbar topbarcolor card size width loader * = required

The free HR calculators and the rules behind them by country.

Try asking: «Calculate end of service in Iraq»

• calculate_hr Reads only

  Run one of mihnaro.com's free HR calculators for a country (ISO code, default IQ; list_calculator_countries lists the ones with rules) and get the breakdown, the total and the rules used, each with its source and basis "law" (verified on an official page), "confirmed" (the company accountant), "owner" (the owner, 2026-11-02) or "estimate". A calculator runs only when every rule it uses is verified against an official source; otherwise the answer is an error with code "not_confirmed", the rules not confirmed and the country's "requires confirmation" list. Results are not legal or tax advice; nothing is stored. tool: end-of-service (start_date, end_date as Y-m-d, basic; optional days_per_year, leaving_reason termination|resignation, min_years, unused_leave_days) | net-salary (basic; allowances, marital_status single|married, ss_employee_percent) | gross-salary (net; allowances, marital_status, ss_employee_percent) | overtime (basic; hours, rest_day_hours, holiday_hours, multiplier, rest_day_multiplier, holiday_multiplier, hours_per_day) | leave (basic; encash_days, unpaid_days, day_base) | cost-to-company (basic; allowances, other_monthly, annual_extras, marital_status, ss_employee_percent, ss_employer_percent). Some countries add region (state, province or region code), children (household tax) or month (1–12, cumulative tax) to the salary tools. The inputs a country takes are in list_hr_calculators. Money is monthly, in the country's currency. Same as GET /api/v1/tools/calculators/{tool}.

  Needs: No single permission: it follows your role and branches

  Parameters: tool* inputs* country variant date * = required

• get_calculator_country Reads only

  One country's calculator rules in force (per variant): every rule's value, its source (law, article, official URL, the date it was read) and whether it is verified, the tools available and notes. available=false when the country has no rules yet. Same as GET /api/v1/tools/countries/{code}.

  Needs: No single permission: it follows your role and branches

  Parameters: country* * = required

• list_calculator_countries Reads only

  The countries mihnaro.com's free HR calculators have rules for: each with the tools it can run, its variants (e.g. nationals and expatriates), currency and how many of its rules are verified. A country not listed is "not available yet". Same as GET /api/v1/tools/countries.

  Needs: No single permission: it follows your role and branches

• list_hr_calculators Reads only

  The free HR calculators of mihnaro.com for a country (ISO code, default IQ): each tool with whether it is available there, its inputs, and the country's rates in force. Same as GET /api/v1/tools/calculators?country=.

  Needs: No single permission: it follows your role and branches

  Parameters: country variant date * = required

Reading these help articles.

Try asking: «How do I add a public holiday?»

• get_help_article Reads only

  One public help center article (docs/help-center.md) by `category` and `slug` from search_help_center: its title, summary, HTML body, sections and link, in English, or Arabic with `locale: ar`.

  Needs: No single permission: it follows your role and branches

  Parameters: category* slug* locale * = required

• search_help_center Reads only

  The public help center at help.mihnaro.com (docs/help-center.md): its topics, and its articles matching a search (`query`) or in a topic (`category`), with their title, summary and link. In English, or Arabic with `locale: ar`. Read one with get_help_article.

  Needs: No single permission: it follows your role and branches

  Parameters: query category locale * = required

Customer companies and licenses, platform admins, support sessions, security policy, email, the server monitor, mobile app rules, broadcasts and the ZenHR sync.

Try asking: «Which licenses end this month?»

• add_backup_folder_destination Changes data

  Add another folder on this server as a backup destination (docs/backups.md). A full path outside the app and web folders, empty or new. It does not survive losing the server. S3 and SFTP take keys, so they are added in the panel or the API.

  Needs: platform.backups_change

  Parameters: name* path* enabled keep_daily keep_weekly keep_monthly * = required

• add_license Changes data

  Renew or change a company's license by adding a new one (history is kept). It applies from its start date. max_branches cannot be lower than the branches the company already has.

  Needs: Any platform admin

  Parameters: company_id* modules* max_employees* max_branches* starts_on* ends_on* notes * = required

• buddy_punching_defaults Changes data

  The platform default of each buddy-punching layer, which every company has until it sets its own (platform.app_control, docs/attendance-security.md §19). All start off. action get: each layer's mode and settings, and the companies with their own. action set with layer bp_face|bp_device_key|bp_presence|bp_pattern and mode off|flag|refuse (bp_pattern can only flag), plus the layer's settings. Same API: GET platform/buddy-punching, PUT platform/buddy-punching/{layer}.

  Needs: platform.app_control

  Parameters: action* layer mode * = required

• cancel_broadcast Changes data

  Cancel a platform broadcast that hasn't started yet: a scheduled one, or one still waiting for the queue (docs/platform-control.md).

  Needs: platform.broadcast

  Parameters: broadcast_id* * = required

• check_company_field_availability Reads only

  Whether a value is free before creating or editing a company: name_en / name_ar (compared without case, spaces, punctuation, Arabic diacritics or tatweel, with alef forms, taa marbuta/haa and yaa/alef maqsura folded; either name of another company counts), slug, owner_email (any account's email), personal_email, phone (E.164; 0770… is read as Iraqi), tax_number (another company's branch), company_email (another company's contact email). Returns available, the normalized value, the message and the company that holds it. Pass company_id / user_id when editing so their own values don't count. create_company and update_company refuse taken values with the same messages.

  Needs: Any platform admin

  Parameters: field* value* company_id user_id * = required

• company_deletion_preview Reads only

  What deleting a company would lose: its payroll runs, attendance records, employees and accounts; real: true means delete_company needs force. Needs platform.companies.

  Needs: platform.companies

  Parameters: company_id* * = required

• create_company Changes data

  Onboard a customer company: creates the company, its first license, its main branch and the company admin (owner). Returns the owner's one-time temporary password when a new user was created; they must change it at first sign-in.

  Needs: Any platform admin

  Parameters: name* slug* country* timezone notes license* main_branch* owner* * = required

• create_platform_admin Changes data

  Add a Mihnaro platform admin (name, email, permissions). Returns a temporary password once; they choose their own at the first sign-in. An email of a company account is refused; a former platform admin gets the access back. Needs platform.admins.

  Needs: platform.admins

  Parameters: name* email* permissions * = required

• delete_backup_destination Changes data

  Remove a backup destination (docs/backups.md). New copies stop going there; copies already stored there stay there. Refused for the only destination that is on.

  Needs: platform.backups_change

  Parameters: destination_id* * = required

• delete_company Can delete

  Delete a company (docs/company-management.md). Needs confirm_name (its English or Arabic name, or its slug, typed exactly) and confirm: true. Refused while it has payroll runs or attendance unless force: true. A backup of every row is written first; the company is hidden at once and can be restored (restore_company) for the restore window (30 days), then it is removed for good. The other platform admins are emailed. Call company_deletion_preview first to see what it holds. Needs platform.companies.

  Needs: platform.companies

  Parameters: company_id* confirm_name* confirm* force reason * = required

• delete_license Can delete

  Delete a license entered by mistake. Refused for the company's only license and for the license in effect (add a newer one or suspend it first). Kept in the activity log. Needs platform.companies.

  Needs: platform.companies

  Parameters: company_id* license_id* * = required

• delete_system_announcement Can delete

  Delete a system announcement that nobody has seen yet. One that was already shown can only be switched off (save_system_announcement with is_active false), so its numbers stay.

  Needs: platform.broadcast

  Parameters: id* * = required

• device_data_defaults Changes data

  The platform defaults every company has until it sets its own in Mobile app rules (platform.app_control, docs/platform-control.md «الموقع شرط لفتح التطبيق» and «بيانات الهاتف»). action get: location_required {enabled, precise, reason_en, reason_ar} (the app shows a full-screen gate until location is on, and the server refuses the company's app calls with location_required; never for demo or store-reviewer accounts), categories {device|network|battery|permissions|security|time|locale|health: {enabled, retention_days 7–730}}, and the companies with their own. action set: any of location_required and categories (only what is given changes). Same API: GET/PUT /api/v1/platform/device-data.

  Needs: platform.app_control

  Parameters: action* location_required categories * = required

• end_support_session Changes data

  End a support session now; the admin is taken out of the company on their next click.

  Needs: Any platform admin

  Parameters: support_session_id* * = required

• event_location_default Changes data

  Keeping the phone's own GPS point with app sign-ins, app opens and version changes, the platform default (platform.app_control, docs/platform-control.md «موقع الأحداث»): what every company has until it sets its own in Mobile app rules (policy event_location). action get: mode, who changed it last, and the companies with their own setting. action set: mode auto (on for companies with live location or the clock-in geofence) | on | off. Only from people who already allowed location on the phone; demo and store-reviewer accounts are never recorded; points older than 10 minutes or from a fake-location app are dropped.

  Needs: platform.app_control

  Parameters: action* mode * = required

• export_platform_notification_log Reads only

  The platform notifications log as a file (platform.notifications, docs/notifications.md), as GET /api/v1/platform/notification-log/export: tab notices, broadcasts or emails with the same filters as list_platform_notification_log (at most 10,000 rows), or send (a notice id) for that notice's recipients. format csv (default) or xlsx. Returns filename, mime, size and the file as base64.

  Needs: platform.notifications

  Parameters: tab format send from to company category channel status kind q * = required

• get_ai_settings Reads only

  The platform AI provider, model and on/off switch (docs/ai.md), and whether a key is saved. The key itself is never returned.

  Needs: platform.ai

• get_app_debug_report Reads only

  One phone diagnostics report in full (docs/mobile-debug.md): the phone's state (version, server, account, permissions, push, location and camera permission, offline drafts, clock skew, certificate pins) and its recent requests (method, path, status, time) and errors. Redacted: no tokens, passwords, bodies, photos, face data or coordinates.

  Needs: Any platform admin

  Parameters: id* * = required

• get_app_person_activity Reads only

  One person's phones with the Mihnaro app and their sign-in activity (docs/platform-control.md "Phone activity"): each phone as in list_app_phones (version, state, push, first and last IP with the local GeoIP place) with its latest 30 events, and other_activity: events not tied to a known phone (sign-ins from an app too old to send its device id). user_id is required. Needs platform.app_control. Plus map_points, the events map (docs/platform-control.md «خريطة الأحداث»): [{type clock_in|clock_out|field_photo|sign_in|sign_in_failed|sign_out|app_open|other, event, at, lat, lng, approximate (true = a city from the local GeoIP for the event's IP), accuracy, place, event_id (its timeline row), install_id}], newest first; GPS points (punches, Field proof photos) only with the location permission (map_gps). Event GPS (docs/platform-control.md «موقع الأحداث»): every event row has has_gps (whether the app sent its own GPS point with it: sign_in, app_open, version_changed); with the location permission (platform.phones.location, or live_location.view in scope) the row also carries location {lat, lng, accuracy, at, source app_event, mocked}. Without it only the IP place shows, which is approximate (a city). map_points now also include live-location pings (type live) and the app's own GPS with events; each point has source punch|live|field|app_event|ip (ip = approximate, from the IP); map_gps_hidden = GPS points exist that this viewer may not see.

  Needs: live_location.view platform.app_control platform.phones.location

  Parameters: user_id* * = required

• get_app_person_context Reads only

  A person's phone details from the Mihnaro app across companies (platform.app_control, docs/platform-control.md «بيانات الهاتف»): phones with location_state and the latest of each category (device, network, battery, permissions, security, time, locale, health), and the history [{at, trigger open|resume|sign_in|punch, category, data}]. Filters: install_id, category, limit. Same API: GET /api/v1/platform/app-fleet/people/{id}/context.

  Needs: platform.app_control

  Parameters: user_id* install_id category limit * = required

• get_app_releases Reads only

  The mobile app release rules (docs/platform-control.md): per platform (android, ios) the latest and minimum version, the version actually required (the latest when update_mode is force), the store link and message; plus each company's own rule (stricter or exempt), the versions a minimum can be picked from (known_versions), and each store's last check (store_checks; the latest version is read from the stores, never typed). Pass platform and version to see what that version would get: ok, suggest or force; add company_id for that company's rule.

  Needs: platform.app_control

  Parameters: platform version company_id * = required

• get_app_update_impact Reads only

  Before forcing a mobile app update (docs/platform-control.md): how many signed-in phones and people would get the update screen (426) if the platform required this version, against how many are blocked today. Without version: forcing today's latest version. Company rules (stricter, exempt) still apply; phones that never reported their version are counted as unknown, not blocked.

  Needs: platform.app_control

  Parameters: platform* version * = required

• get_backup_connect_link Changes data

  A link for the admin to open in a browser signed in to the panel, to connect a Google Drive, OneDrive or Dropbox destination to his own account (docs/backups.md). The sign-in happens on the service. It lasts 15 minutes. The link holds no secret.

  Needs: platform.backups_change

  Parameters: destination_id* * = required

• get_backup_run Reads only

  One backup in full (docs/backups.md): its parts and checksums, each copy, the row count of every table, and its restore tests.

  Needs: platform.backups

  Parameters: run_id* * = required

• get_backup_status Reads only

  The automatic backups now (docs/backups.md): settings, next run, problems, the 3-2-1-1-0 checks, RPO and measured RTO, last good backup, last restore test, and destinations. Never holds a secret.

  Needs: platform.backups

• get_broadcast_preview Reads only

  Before a platform broadcast (docs/platform-control.md): how many people the audience reaches, how many have the mobile app (and how many working phones), how many have an email, and push status (enabled, fcm.configured, apns.configured: sent straight to Google and Apple). company_ids empty = every company; roles (owners, hr, employees) empty = everyone; user_ids, branch_ids, install_ids, platform, version_state and version narrow it to those people, branches and phones.

  Needs: platform.broadcast

  Parameters: company_ids roles user_ids branch_ids install_ids platform version_state version * = required

• get_company Reads only

  Get one company with its current license, full license history, branches and owners.

  Needs: Any platform admin

  Parameters: company_id* * = required

• get_domains Reads only

  Mihnaro's six domains (marketing, app, admin, api, help, demo) with each one's address, and the live demo's state: enabled, ready, when it was last rebuilt and its nightly reset time.

  Needs: Any platform admin

• get_flash_messages Reads only

  How the web app shows its save, edit, delete and error messages, for everyone (docs/flash-messages.md): position (top-center, top-start, top-end, center, bottom), duration_seconds (2 to 30), auto_close. Errors stay until closed whatever is set. last_change {by, at} is null while it is the default.

  Needs: platform.flash_messages

• get_mail_health Reads only

  Is email going anywhere (docs/mail.md): status ok | failing | not_delivering, the sending method (driver "log" and "disabled" deliver nothing), a plain message, counts for the last 24 hours (sent, logged, queued, failed), how many wait in the queue, and the last failure. "sent" means handed to the SMTP server, not proof of reaching an inbox.

  Needs: Any platform admin

• get_messaging_status Reads only

  Email and WhatsApp settings without secrets: driver, sender details, whether a password/token is saved, and whether each channel is ready to send reset links.

  Needs: Any platform admin

• get_platform_limits Reads only

  Every limit at platform level (docs/limits.md): file sizes, counts and lengths, each with its default, its allowed range, the value saved and the server's ceiling for files.

  Needs: Any platform admin

• get_security_policy Reads only

  Read the security policy: lockout, password rules and expiry, reset links, sessions and "Remember me".

  Needs: Any platform admin

• get_server_history Reads only

  Server metrics over time (docs/server-monitor.md), as chart series: cpu, load1, memory, swap, disk (% of the fullest mount), disk_read/disk_write and net_rx/net_tx (bytes/s), db_connections, errors and db_timeouts (the most in one minute). range 24h = 5-minute points, 7d = hourly, 30d = 4-hourly. Kept 30 days.

  Needs: server.monitor

  Parameters: range * = required

• get_server_overview Reads only

  The server right now (docs/server-monitor.md): CPU per core and load, RAM/swap, every disk (usage, inodes, I/O), network, uptime, hardware, services (Nginx, PHP-FPM, PostgreSQL, Cloudflare Tunnel, cron), PostgreSQL connections/sizes/long queries/locks, Laravel errors and database connection timeouts, failed jobs, the ZenHR sync, biometric devices last seen, the newest backup, HTTPS/SSL of the public sites, whether email is delivered, push status (FCM and APNs configured yes/no; sent straight to Google and Apple), and alert_values (each alert metric now). Read-only. Pass section to get one part only.

  Needs: server.monitor

  Parameters: section * = required

• get_server_switch Reads only

  Whether the mobile app's hidden live/dev switch works now (docs/mobile-server-switch.md): on, until (when it turns itself off; null = only by hand), by and at (who changed it last and when). Off by default. While off, 15 taps do nothing, and a phone on dev goes back to the live server at its next open.

  Needs: Any platform admin

• get_sign_in_options Reads only

  The sign-in screen switches for the mobile app and the web sign-in page (docs/platform-control.md): forgot_password, sso, privacy (true = shown). Off hides the link and the server refuses forgot-password and SSO with 403. The privacy switch only hides the sign-in link; Settings always keeps the privacy policy. last_change {by, at} is null while they are the defaults (all on).

  Needs: platform.app_control

• get_zenhr_connection Changes data

  A company's ZenHR connection: status, where its keys are kept, masked keys, branches and last success. Never returns a secret. Keys are typed by a person in the panel; no MCP tool takes them.

  Needs: platform.zenhr

  Parameters: company_id* * = required

• get_zenhr_health Changes data

  The sync's state for a company: running, paused or idle, next run, last run, last success, failures, open conflicts and alerts. Times carry the company's offset (Baghdad: +03:00). Read-only.

  Needs: platform.zenhr

  Parameters: company_id* * = required

• get_zenhr_payroll_compare Changes data

  The last payroll comparison: ZenHR's figures against Mihnaro's engine, totals only.

  Needs: platform.zenhr

  Parameters: company_id* * = required

• get_zenhr_run Changes data

  One run: counts per type, progress while running, and the records it touched (table, reference, column names; never values).

  Needs: platform.zenhr

  Parameters: company_id* run_id* action per_page * = required

• get_zenhr_sync Reads only

  The ZenHR → Mihnaro sync of a company (until the move is final): whether it is on, whether ZenHR's API is configured, its ZenHR branches, open flagged rows and the last 10 runs with counts per area (inserted, updated, unchanged, skipped, flagged). Counts only, never employee data.

  Needs: platform.zenhr

  Parameters: company_id* * = required

• get_zenhr_totals Changes data

  ZenHR and Mihnaro totals per branch and list: records read through the API against the rows they became. Counts only.

  Needs: platform.zenhr

  Parameters: company_id* * = required

• list_ai_models Reads only

  The models the chosen AI provider offers the saved key, read live from the provider (docs/ai.md). fresh: true skips the six-hour copy.

  Needs: platform.ai

  Parameters: fresh * = required

• list_app_activity Reads only

  Phone activity (docs/platform-control.md "Phone activity"): what happened on phones with the Mihnaro app, newest first. Each event has event (sign_in, sign_in_failed, sign_out, app_open, version_changed, push_registered, push_result, push_test, device_pending, device_approved, device_blocked, device_reset, device_mismatch), result (ok, failed, blocked), time, person, install_id, device_id, IP and place from the local GeoIP (country, city, ASN, organisation; approximate, never looked up outside), app version, system, model, who decided (actor) and detail (a failed sign-in's reason and half-hidden login, a version change's from/to, a push error; push_result and push_test also have push_reason, the answer in plain words). Filters: user_id, install_id (a phone from list_app_phones: its own timeline), device_id, event, result, from, to (dates); page, per_page (max 200). Needs platform.app_control. Event GPS (docs/platform-control.md «موقع الأحداث»): every event row has has_gps (whether the app sent its own GPS point with it: sign_in, app_open, version_changed); with the location permission (platform.phones.location, or live_location.view in scope) the row also carries location {lat, lng, accuracy, at, source app_event, mocked}. Without it only the IP place shows, which is approximate (a city).

  Needs: live_location.view platform.app_control platform.phones.location

  Parameters: user_id install_id device_id event result from to page per_page * = required

• list_app_debug_reports Reads only

  Phone diagnostics (docs/mobile-debug.md): the accounts with the app's debug mode (on, until, by) and the newest reports their phones sent (kept 14 days). Filters: user_id, install_id, build. Read one with get_app_debug_report.

  Needs: Any platform admin

  Parameters: user_id install_id build * = required

• list_app_phones Reads only

  Phones and versions (docs/platform-control.md): every phone the Mihnaro app is signed in on, with its person, companies, branches, platform, system version, model, app version and build, state (below_min = refused with 426, outdated, latest, newer = above the store's latest (a test build), store_unknown = the store's latest isn't known yet, unknown = an old app before 1.1 that never reported its version), the last GPS location (location: the newest punch, live-location ping or Field proof point from that phone; only with platform.phones.location), push status (active, failing, none; last accepted/failed and the provider's error) and first/last seen; plus the summary per platform (people per version, below the minimum, people who never opened the latest version, % on the latest). Filters: q, company_id, branch_id, platform, version, state, push, signed_in, seen_days, shared (only phones used by more than one account; each row has shared {accounts, others, list} when it is); page, per_page (max 200).

  Needs: platform.app_control platform.phones.location

  Parameters: q company_id branch_id platform version state push signed_in shared seen_days page per_page * = required

• list_backup_restore_tests Reads only

  The restore tests, newest first (docs/backups.md): result, where the copy came from, tables, rows and files compared, how long it took, and any counts that did not match.

  Needs: platform.backups

  Parameters: limit * = required

• list_backup_runs Reads only

  The backup history, newest first (docs/backups.md): status, size, duration, checksums, copies at each destination, and any error.

  Needs: platform.backups

  Parameters: limit * = required

• list_branches Reads only

  List a company's branches with country, currency, timezone, main/active flags and logo URLs, plus how many more the license allows.

  Needs: Any platform admin

  Parameters: company_id* * = required

• list_broadcasts Reads only

  Platform broadcasts (docs/platform-control.md), newest first, with who sent them and counts per result: push accepted (Google FCM or Apple APNs took it for delivery, sent directly with no relay; not proof it was shown) | failed | no_device | not_configured (the provider of that phone has no credentials yet) | disabled (push switched off) | sent_to_expo (older sends through Expo), receipts pending | ok | error (only on older Expo sends), email sent | logged (not delivered) | queued | skipped | off (mail switched off) | failed | no_email. Pass id for one with up to 200 of its people (result filters by push result).

  Needs: platform.broadcast

  Parameters: id result * = required

• list_companies Reads only

  List customer companies with their current license status, modules, limits and owners. Search by name or slug, filter by status.

  Needs: Any platform admin

  Parameters: search status page * = required

• list_company_users Reads only

  List a company's accounts a page at a time, as the admin panel's table does: search by name or email, filter by role (admin, user) and status (active, temporary, disabled), sort (name, email, role, status, joined).

  Needs: Any platform admin

  Parameters: company_id* q role status sort dir per_page page * = required

• list_deleted_companies Reads only

  The deleted companies still restorable: when and why each was deleted, whether it was forced, its backup file and the date it is removed for good. Needs platform.companies.

  Needs: platform.companies

• list_mail_deliveries Reads only

  Emails the app handed to a mailer, newest first (docs/mail.md): recipient, subject, company, via (smtp, company_smtp, log), status (sent, logged, queued, failed), attempts and the error in plain words. Filter by status or search an address/subject. Kept 90 days.

  Needs: Any platform admin

  Parameters: status q limit * = required

• list_monitor_alert_events Reads only

  The server alerts log, newest first (docs/server-monitor.md): fired, repeat (still lasting after the cooldown) or recovered, the value and threshold, the message, the recipients and mail_result (sent, logged = written to the server log only and not delivered, queued, skipped, failed, no_recipients).

  Needs: server.monitor

  Parameters: kind metric limit * = required

• list_monitor_alert_rules Reads only

  Server alert rules (docs/server-monitor.md): metric, threshold (fires at_or_above, or at_or_below for ssl_days), for_minutes it must last, cooldown_minutes between reminders, enabled, state ok|firing and the last value; plus the recipients and the alert language.

  Needs: server.monitor

• list_platform_admins Reads only

  List the Mihnaro team's platform admins with their platform permissions and status (temporary password, two-step). Filter by search (name or email) or one permission. Also returns every permission there is and what it allows. Needs platform.admins.

  Needs: platform.admins

  Parameters: search permission * = required

• list_platform_notification_log Reads only

  The platform notifications log (platform.notifications, docs/notifications.md "سجل إشعارات المنصة"), as GET /api/v1/platform/notification-log. tab notices (default): every company's notices with category, event, text en/ar, company, triggered_by, recipients, bell read counts and per channel (push, email, whatsapp) each status count (logged = written to the server log only, NOT delivered), plus summary; filters from, to, company, category, channel, status, kind, q. tab broadcasts: the Mihnaro team's push broadcasts with their results; filters from, to, q. tab emails: system emails that are not notice copies (password resets, invitations, codes, reports) from the mail log; filters from, to, company, status (sent, logged, queued, failed), q. Also returns channels: whether email, push and WhatsApp can deliver right now.

  Needs: platform.notifications

  Parameters: tab from to company category channel status kind q page limit * = required

• list_support_sessions Reads only

  The support audit trail of a company: every time a platform admin opened its account, with the reason, times, state and how it ended. Newest first.

  Needs: Any platform admin

  Parameters: company_id* * = required

• list_system_announcements Reads only

  System announcements from the Mihnaro team (docs/platform-control.md), newest first, optionally by state (live, scheduled, ended, off). Pass id for one with its stats: audience (people it is meant for now), seen, dismissed, acknowledged.

  Needs: platform.broadcast

  Parameters: id state * = required

• list_zenhr_audit Changes data

  The sync's audit log: who changed what, when and from where. Secrets are never recorded.

  Needs: platform.zenhr

  Parameters: company_id* action per_page * = required

• list_zenhr_data_types Changes data

  What moves: each data type with on/off, how often, starting point, how it arrives, and what the code cannot do. With branch_id: that branch's values.

  Needs: platform.zenhr

  Parameters: company_id* branch_id * = required

• list_zenhr_runs Changes data

  The company's run history, newest first: who started each, its counts, duration and errors in plain words. Paused hours are left out unless status=off.

  Needs: platform.zenhr

  Parameters: company_id* status trigger per_page * = required

• list_zenhr_sync_conflicts Reads only

  Rows the ZenHR sync flagged instead of overwriting: changed in ZenHR and also edited in Mihnaro (reason "edited"), or imported before the baseline (reason "no_baseline"). Gives the table, row id, external_ref and the column names involved, not their values.

  Needs: platform.zenhr

  Parameters: company_id* status limit offset * = required

• phone_sharing_default Changes data

  One account per phone, the platform default (platform.app_control, docs/platform-control.md «الهاتف المشترك»): what every company has until it sets its own in Mobile app rules. action get: mode, max_accounts, who changed it last, and the companies with their own setting. action set: mode allow (only marked as shared) | warn (sign-in goes through, the phone is flagged, the company is notified) | block (the sign-in is refused with a message to ask HR), max_accounts 1–10. Demo and store-reviewer accounts are never stopped. Shared phones themselves: list_app_phones with shared=true.

  Needs: platform.app_control

  Parameters: action* mode max_accounts * = required

• remove_platform_admin Changes data

  Remove a platform admin's access: no admin panel, no permissions, their platform API keys revoked and their sessions ended. The account stays; create_platform_admin with the same email gives it back. The last admin with platform.admins can't be removed. Needs platform.admins.

  Needs: platform.admins

  Parameters: admin_id* * = required

• reset_company_user_password Can delete

  Replace a company user's password with a new temporary one they must change at next sign-in. The old password stops working immediately. Returns the temporary password once.

  Needs: Any platform admin

  Parameters: company_id* user_id* * = required

• reset_demo Can delete

  Rebuild the live demo's sandbox company (demo.mihnaro.com) now with fresh fictional data, instead of at the nightly reset. Visitors inside it are signed out.

  Needs: Any platform admin

• reset_user_two_factor Can delete

  Turn off a company user's two-step verification (lost phone), so they set it up again. Their recovery codes stop working.

  Needs: Any platform admin

  Parameters: company_id* user_id* * = required

• resolve_zenhr_sync_conflict Can delete

  Settle a row the ZenHR sync flagged: "apply" writes ZenHR's values over the Mihnaro edit; "keep" leaves Mihnaro's row and stops flagging the same ZenHR values (a later ZenHR change is flagged again).

  Needs: platform.zenhr

  Parameters: company_id* conflict_id* action* * = required

• restore_company Changes data

  Restore a deleted company within its restore window: it shows again and its people can sign in. Needs platform.companies.

  Needs: platform.companies

  Parameters: company_id* * = required

• resume_zenhr_run Changes data

  Starts a new run with what a stopped or failed run was given. What it finished is not done twice.

  Needs: platform.zenhr

  Parameters: company_id* run_id* * = required

• retry_mail_delivery Changes data

  Put one failed email (from list_mail_deliveries, retryable true) back in the queue; it goes out within a minute through the current settings. Only when the person asked to resend it.

  Needs: Any platform admin

  Parameters: delivery_id* * = required

• run_backup Changes data

  Start a backup now (docs/backups.md). It starts within a minute and never overlaps another; read get_backup_run for its result.

  Needs: platform.backups_run

• run_backup_restore_test Changes data

  Restore one backup into a new throwaway database and compare its row counts (docs/backups.md). It starts within a minute. It never touches a real database; there is no tool that does.

  Needs: platform.backups_run

  Parameters: run_id* * = required

• run_zenhr_payroll_compare Changes data

  Queues a payroll comparison of the last months: recalculated and rolled back, so it changes nothing. Takes the sync's lock.

  Needs: platform.zenhr

  Parameters: company_id* months * = required

• run_zenhr_sync Changes data

  Queue a ZenHR → Mihnaro sync run: one at a time, refused while another runs. source "api" reads what changed through ZenHR's API; "extraction" applies a new extraction. dry_run rolls everything back and only reports counts: do it first. data_types (list_zenhr_data_types), branch_ids and since (a date, API only, not for attendance) narrow it. Follow it with get_zenhr_run.

  Needs: platform.zenhr

  Parameters: company_id* source dry_run data_types branch_ids since * = required

• save_company_branch Changes data

  Add a branch to a company (no branch_id; within the license's branch limit) or edit one: names, code, legal name, country, currency, timezone, city, active, main (is_main: true makes it the main branch) and the governmental details. Logos are uploaded through the API. Needs platform.companies.

  Needs: platform.companies

  Parameters: company_id* branch_id name legal_name code country currency timezone city is_active is_main establishment_number establishment_name governance_location ss_number ss_governance_location tax_number address po_box zip_code mol_number * = required

• save_system_announcement Changes data

  Create a system announcement shown after sign-in (docs/platform-control.md), or change one by id (only what is passed changes; is_active false withdraws it). New ones need title_en, title_ar, body_en, body_ar, severity (info|warning|critical), starts_at, channel (web|app|both) and display (dismissible|acknowledge). ends_at optional. company_ids empty = every company; roles (owners, hr, employees) empty = everyone.

  Needs: platform.broadcast

  Parameters: id title_en title_ar body_en body_ar severity starts_at ends_at company_ids roles channel display is_active existing_only * = required

• send_app_update_reminder Changes data

  "Please update" (docs/platform-control.md): a push to the people whose phone on this platform runs an older version than the latest (version_state outdated, the default) or one below the minimum (below_min), linking to the store, with the release's update message (or a default text). Needs platform.app_control and platform.broadcast. Goes out in the background; follow it with list_broadcasts.

  Needs: platform.app_control platform.broadcast

  Parameters: platform* version_state * = required

• send_broadcast Changes data

  Send a push notification (and optionally an email) to every company or chosen ones (docs/platform-control.md). Check get_broadcast_preview first. Needs title_en, title_ar, body_en, body_ar; url (an app path starting with / or an https link, opened on tap) optional; push (default true), email (default false). Narrow it with user_ids, branch_ids, install_ids (phones from list_app_phones), platform, version_state (outdated, below_min, latest, unknown = an old app before 1.1 that never reported its version) or version (exact); scheduled_at (a future date and time) sends it later; test=true sends it now only to your own phones and email. Images are added from the admin panel or the API (an uploaded file). It goes out in the background in batches; follow it with list_broadcasts. "accepted" means Google (FCM) or Apple (APNs) took it for delivery, sent straight from the server; it is not proof the phone showed it. iPhones get nothing until APNs is configured (see get_server_overview push).

  Needs: platform.broadcast

  Parameters: title_en* title_ar* body_en* body_ar* url push email scheduled_at test company_ids roles user_ids branch_ids install_ids platform version_state version * = required

• send_phone_test_push Changes data

  One test notification to one phone (docs/notifications.md «الإشعار التجريبي»): install_id from list_app_phones. Straight to Apple or Google, nothing in the bell, logged on the phone's timeline (push_test) with who sent it. Returns sent and, per token: provider, status (ok, invalid, error), error, environment (which of Apple's servers took it), fallback (the first server refused it) and reason in plain words. "ok" means accepted for delivery, not shown on screen. At most 5 a minute per phone. Needs platform.app_control.

  Needs: platform.app_control

  Parameters: install_id* * = required

• send_test_email Changes data

  Send one test email through the platform email settings saved in Admin → Security and messaging (docs/mail.md). A failure says why in plain words (wrong username or password, connection refused, encryption and port mismatch, sender refused…). result "sent" means the server accepted it (not that it reached the inbox); "logged" means it was only written to the server log. Only send when the person asked for a test.

  Needs: Any platform admin

  Parameters: to* * = required

• set_company_app_rule Changes data

  One company's own mobile app update rule (docs/platform-control.md). mode stricter: its people need at least min_android / min_ios (or the platform minimum if higher); exempt: they are never blocked for an old version; none: remove the rule.

  Needs: platform.app_control

  Parameters: company_id* mode* min_android min_ios note * = required

• set_company_user_access Changes data

  Switch a company account on or off (is_active) and make it a company admin or not (is_owner). The company always keeps one active company admin; a platform admin can't be one. Logged. Needs platform.companies.

  Needs: platform.companies

  Parameters: company_id* user_id* is_active is_owner * = required

• set_monitor_alert_recipients Changes data

  Who receives server alerts (docs/server-monitor.md): the full list of addresses (replaces the saved one; an empty list stops alert emails) and the language, en or ar. Only addresses the person gave. While email is in log mode nothing is delivered (see get_mail_health).

  Needs: server.monitor

  Parameters: recipients* language * = required

• set_zenhr_emergency_stop Changes data

  The emergency stop: on stops every company's sync at once, a run in progress included; off lifts it.

  Needs: platform.zenhr

  Parameters: on* * = required

• show_platform_notification_log Reads only

  One company notice of the platform notifications log in full (platform.notifications, docs/notifications.md), as GET /api/v1/platform/notification-log/{id}: the send, every person with branch, bell (read and when), push (per phone what Google/Apple answered), email (status, mail log row with via, attempts and error) and WhatsApp, and the receiver emails.

  Needs: platform.notifications

  Parameters: id* * = required

• start_support_session Changes data

  Open a support session in a company as the signed-in platform admin. Returns a one-time entry_url (valid 2 minutes) that signs the admin into the company's account in a browser. Give the link only to that admin. A reason is required and is kept in the audit trail.

  Needs: Any platform admin

  Parameters: company_id* reason* * = required

• stop_zenhr_run Changes data

  Stops a queued or running run. A running one stops at its next safe place; what finished stays.

  Needs: platform.zenhr

  Parameters: company_id* run_id* * = required

• suspend_license Changes data

  Suspend a license (suspended: true) or reactivate it (false). A suspended license does not count: the license before it applies again, or with none the company's users can't sign in. Needs platform.companies.

  Needs: platform.companies

  Parameters: company_id* license_id* suspended* * = required

• switch_zenhr_branch Changes data

  Pauses or resumes one branch's sync.

  Needs: platform.zenhr

  Parameters: company_id* branch_id* enabled* * = required

• switch_zenhr_sync Changes data

  Turn a company's ZenHR → Mihnaro sync on or off. Turn it off when employees have moved to Mihnaro for good. It also needs ZENHR_SYNC_ENABLED=true on the server to run.

  Needs: platform.zenhr

  Parameters: company_id* enabled* * = required

• sync_app_stores Changes data

  Read the app's latest version from the App Store (Apple's public lookup) and Google Play (the Play Developer API when PLAY_SERVICE_ACCOUNT is configured, otherwise the public Play listing) now, as the hourly check does (docs/platform-control.md). Returns each check (ok, failed or not_configured) and the releases.

  Needs: platform.app_control

• test_backup_destination Changes data

  Writes, reads and removes a small file at a backup destination and says what it found (docs/backups.md).

  Needs: platform.backups_change

  Parameters: destination_id* * = required

• test_zenhr_connection Changes data

  Makes one real read call to ZenHR to see the connection works. Refused while a sync runs. Ask a person before calling it.

  Needs: platform.zenhr

  Parameters: company_id* * = required

• unlock_user Changes data

  Lift the lock on a company user after too many failed sign-ins.

  Needs: Any platform admin

  Parameters: company_id* user_id* * = required

• update_ai_settings Changes data

  Change the platform AI provider, model or on/off switch (docs/ai.md). provider: anthropic, openai or none. model: an id from list_ai_models, empty for the default. enabled: boolean. The key is only typed in the admin panel.

  Needs: platform.ai

  Parameters: provider model enabled * = required

• update_app_debug_account Changes data

  Turn the app's debug mode on or off for one account (docs/mobile-debug.md). user_id or email; on (boolean); hours (1–168, default 24; null = no end); send (true asks its phone for a report at its next open). The person sees a band on the phone while it is on. Recorded with your name and emailed to the other platform admins with platform.app_debug.

  Needs: platform.app_debug

  Parameters: user_id email on* hours send * = required

• update_app_release Changes data

  Change the mobile app release rule for one platform (docs/platform-control.md): min_version (one of known_versions from get_app_releases; phones older than it get 426 update_required; empty = no minimum), update_mode none|suggest|force (needs the store's latest version), message_en, message_ar, release_notes_en, release_notes_ar ("what's new", shown on the app's update screen). Only what is passed changes. latest_version and store_url are read from the stores (sync_app_stores) and are refused here.

  Needs: platform.app_control

  Parameters: platform* min_version update_mode message_en message_ar release_notes_en release_notes_ar * = required

• update_backup_destination Changes data

  Switch a backup destination on or off and change how many daily, weekly and monthly copies it keeps (docs/backups.md). Refused for the only destination that is on. S3 and SFTP destinations and their keys are entered in the panel or the API, so secrets never pass through a chat.

  Needs: platform.backups_change

  Parameters: destination_id* enabled keep_daily keep_weekly keep_monthly * = required

• update_backup_settings Changes data

  Change the backup schedule and what it includes (docs/backups.md). Only what is passed changes. The passphrase is not set here: it is typed in the panel. The other admins with platform.backups get an email.

  Needs: platform.backups platform.backups_change

  Parameters: enabled frequency every_hours time weekday timezone include_database include_files include_secrets restore_test free_space_factor overdue_grace_hours job_timeout_minutes target_rto_minutes notify_success * = required

• update_company Changes data

  Change a company's details or status. Only the fields given change. Setting status to "suspended" blocks sign-in for all its users; "active" restores it.

  Needs: Any platform admin

  Parameters: company_id* name slug status country timezone notes * = required

• update_flash_messages Changes data

  Change how the web app shows its save, edit, delete and error messages, for every company and user (docs/flash-messages.md). Only what is passed changes. Errors stay until closed whatever is set. The other platform admins with platform.flash_messages get an email.

  Needs: platform.flash_messages

  Parameters: position duration_seconds auto_close * = required

• update_license Changes data

  Edit one of a company's licenses in place (dates, modules, limits, notes); fields left out keep their value. Returns the license and any other licenses whose dates it overlaps: while they overlap, the one that started last is in effect. Needs platform.companies.

  Needs: platform.companies

  Parameters: company_id* license_id* modules max_employees max_branches starts_on ends_on notes * = required

• update_monitor_alert_rule Changes data

  Change one server alert rule (docs/server-monitor.md), found by its metric: threshold, for_minutes (1-1440), cooldown_minutes (5-10080) or enabled. Only what is passed changes. Switching off a firing rule clears it without a recovery email.

  Needs: server.monitor

  Parameters: metric* threshold for_minutes cooldown_minutes enabled * = required

• update_platform_admin Changes data

  Rename a platform admin and change their platform permissions: permissions is the whole list they keep, or grant / revoke one. At least one admin always keeps platform.admins. Needs platform.admins.

  Needs: platform.admins

  Parameters: admin_id* name permissions grant revoke * = required

• update_platform_limits Changes data

  Change limits at platform level (docs/limits.md): values {key: number, or null for the built-in default}, sizes in KB. Only the keys sent change. Companies without their own value follow it at once. See get_platform_limits for the keys.

  Needs: Any platform admin

  Parameters: values* * = required

• update_security_policy Changes data

  Change parts of the security policy; fields not given keep their value. Applies from the next request. See get_security_policy for the fields.

  Needs: Any platform admin

  Parameters: max_attempts lock_minutes password_min_length password_require_mixed_case password_require_numbers password_require_symbols password_expiry_months reset_link_minutes reset_requests_per_hour reset_channels app_idle_minutes admin_idle_minutes expire_on_close remember_me_days admin_remember_me support_session_minutes activity_log_max_months * = required

• update_server_switch Changes data

  Turn the mobile app's hidden live/dev switch on or off (docs/mobile-server-switch.md). on: boolean. hours: how long it stays on (1–168, default 24; null = until turned off by hand). Off: 15 taps do nothing, and phones on dev go back to the live server at their next open; their dev drafts stay on the phone for dev. The other platform admins with platform.server_switch get an email.

  Needs: platform.server_switch

  Parameters: on* hours * = required

• update_sign_in_options Changes data

  Switch the sign-in screen links on or off for the mobile app and the web sign-in page (docs/platform-control.md): forgot_password, sso, privacy (booleans; only what is passed changes). Off hides the link and the server refuses forgot-password and SSO with 403 sign_in_option_off. privacy off hides only the sign-in link: Settings always keeps the privacy policy (Apple 5.1.1, Google Play). The other platform admins with platform.app_control get an email.

  Needs: platform.app_control

  Parameters: forgot_password sso privacy * = required

• update_user_contact Changes data

  Set where the password reset links of a company user go: personal email and WhatsApp phone (+ and country code).

  Needs: Any platform admin

  Parameters: company_id* user_id* personal_email phone * = required

• update_zenhr_data_type Changes data

  Turns a data type on or off (it also pauses that type in a running sync), or sets how often it is read and its starting point. With branch_id: for that branch only. Refuses what the code cannot do.

  Needs: platform.zenhr

  Parameters: company_id* data_type* branch_id enabled frequency starting_from * = required