Payroll
Read-only access to payroll periods, calculation runs and the employee roster. Scopes: payroll:periods:read, payroll:runs:read, payroll:employees:read.
List Periods
Payroll periods. Query: year, status, page, pageSize.
List Calculation Runs
Calculation runs with employee count and aggregate gross/deductions/net totals. Query: periodId, status, page, pageSize.
Get Run Summary
Aggregate totals for a single run — individual payslip lines are intentionally omitted.
List Employees
Active employee roster with summary identity fields only: id, firstName, lastName, fullName, isActive, payrollStatus (no salary, national code or bank data). There is no name, code or status field. Query: search, page, pageSize.
{ "success": true, "data": [ { "id": 168991, "firstName": "Sara", "lastName": "Ahmadi", "fullName": "Sara Ahmadi", "isActive": true, "payrollStatus": null } ], "meta": { "page": 1, "pageSize": 20, "totalCount": 1, "totalPages": 1, "hasMore": false } }
GET /payroll/employees/{id} returns the same fields plus username and mobile. To create a user or an employee, the portal main admin uses POST /admin/users below; everyone else uses the panel (/settings/users).
Portal Users & Employees (main admin only)
Only the active main admin of the same portal can use these endpoints: the token needs admin:users:read / admin:users:write (main-admin and Homa Copilot mirror tokens of a main admin have them), and the caller's HR row is checked live on every request (MainAdmin = 1, active). Acting on another portal with X-Homa-Portal is refused (403 / E1009). Any other caller gets 403 / E1003. Every create, activate, deactivate and password change, and every refused write, is written to an audit log; if the log is unreachable no write is made (503 / E9002). Passwords are never returned or logged. A new user has no roles; assign access in the panel (/settings/users).
All users (with login) and employees (without login) of the portal, active and inactive. Query: search (name, username, mobile), isActive (true/false), isUser (true/false), page, pageSize (max 100). Fields: id, username (null for employees), firstName, lastName, fullName, nickName, mobile, extension, isUser, isActive, isMainAdmin.
Example
curl "https://www.HomaCRM.com/api/v1/external/admin/users?isActive=false" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4"
{ "success": true, "data": [ { "id": 168991, "username": "sara", "firstName": "Sara", "lastName": "Ahmadi", "fullName": "Sara Ahmadi", "nickName": "Sara", "mobile": "09121234567", "extension": "12", "isUser": true, "isActive": false, "isMainAdmin": false } ], "meta": { "page": 1, "pageSize": 20, "totalCount": 1, "totalPages": 1, "hasMore": false } }
Create a portal user or an employee. Body fields (anything else is rejected with 422, nothing is created): firstName*, lastName*, nickName, mobile, extension, isUser (default true: can log in), isActive (default true), and for users username* (unique in the portal, no spaces) and optional password (6–128 characters). Without a password the user sets one through «forgot password» with an SMS code to their own mobile, or the admin sets it later with PATCH /admin/users/{id}. An employee (isUser: false) takes no username or password. Main admins cannot be created here. Errors: 409 / E3002 username taken, 422 / E2002, E2003 invalid body.
Example
curl -X POST "https://www.HomaCRM.com/api/v1/external/admin/users" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Content-Type: application/json" \
-d '{ "firstName": "Mina", "lastName": "Rahimi", "username": "mina", "password": "••••••", "mobile": "09121234567" }'
{ "success": true, "data": { "user": { "id": 168992, "username": "mina", "firstName": "Mina", "lastName": "Rahimi", "fullName": "Mina Rahimi", "nickName": "Mina Rahimi", "mobile": "09121234567", "extension": null, "isUser": true, "isActive": true, "isMainAdmin": false }, "passwordSet": true, "accessNote": "New users start with no roles; assign access in the panel (/settings/users)." } }
One user or employee of the portal (same fields as the list). 404 / E3001 when the id is not in this portal.
Example
curl "https://www.HomaCRM.com/api/v1/external/admin/users/168992" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4"
Activate / deactivate (isActive) and/or set the password (password, users only). Other fields are rejected with 422; change them in the panel. The only active main admin of the portal cannot be deactivated, a main admin cannot deactivate themselves through the API, and no main admin's password can be set here (panel only). Both fields sent together are written in one update. Sending the current state changes nothing. The response shows changes.isActive as before / after.
Example
curl -X PATCH "https://www.HomaCRM.com/api/v1/external/admin/users/168992" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Content-Type: application/json" \
-d '{ "isActive": false }'
{ "success": true, "data": { "user": { "id": 168992, "username": "mina", "isActive": false, "...": "..." }, "changes": { "isActive": { "before": true, "after": false, "changed": true } } } }