{ "openapi": "3.1.0", "info": { "title": "Mawro HRMS API", "version": "1.0", "description": "The Mawro HRMS REST API for integrations: employee and organization data, attendance capture from any device, leave, and payroll journals for your ERP.\n\n- **Base URL:** `https://mawro.neuroskill.tech/api/v1`\n- **Authentication:** `POST /auth/login` returns a JWT access token; send it as `Authorization: Bearer `. Refresh it with `POST /auth/refresh`. Use a dedicated integration user: it sees and does only what its role allows.\n- **API keys:** server-to-server integrations can use the `/ext` endpoints with a workspace API key (`Authorization: Bearer mk_live_…`), limited to the scopes it was given and to 120 requests per minute per key by default.\n- **Responses:** JSON bodies are wrapped as `{ \"data\": …, \"meta\": { \"correlationId\", \"timestamp\" } }`. File downloads are returned as files. Errors use `{ \"error\": { \"key\", \"message\", \"statusCode\", \"details\", … } }`.\n- **Dates:** timestamps are ISO 8601 in UTC; business dates are `YYYY-MM-DD`.\n- **Idempotency:** punch batches carry an `idempotencyKey`; re-sending it returns the original result.\n- **Rate limits:** 600 requests per minute per client; sign-in and token refresh 20 per minute. Exceeding them returns 429." }, "servers": [ { "url": "https://mawro.neuroskill.tech/api/v1", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Authentication", "description": "Sign in, refresh and inspect the session." }, { "name": "Employees", "description": "The employee directory, records and dated facts." }, { "name": "Organization", "description": "Legal entities, departments, locations, positions, grades, cost centers and other effective-dated records." }, { "name": "Attendance", "description": "Punch ingestion from any device, the capture ledger and daily attendance." }, { "name": "Leave", "description": "Leave types, balances and requests." }, { "name": "Payroll", "description": "Payroll runs, GL journals for your ERP, and payslips." }, { "name": "External API", "description": "Server-to-server endpoints under `/ext`, authenticated with a workspace API key (`Authorization: Bearer mk_live_…`) instead of a user session. Keys are created by an administrator under Settings › Integrations, shown once, stored hashed, limited to the scopes chosen, never above their creator's own permissions, rate-limited per key and audited on every call." } ], "paths": { "/auth/login": { "post": { "tags": [ "Authentication" ], "operationId": "login", "summary": "Sign in", "description": "Exchanges a username and password for an access token, a refresh token and the session. Use a dedicated integration user whose role grants only the permissions your integration needs. Limited to 20 attempts per minute per client address.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "username", "password" ], "properties": { "username": { "type": "string", "minLength": 2, "maxLength": 80 }, "password": { "type": "string", "minLength": 6, "maxLength": 200 }, "tenantCode": { "type": "string", "maxLength": 40, "description": "Needed only when signing in through the shared host." } } }, "example": { "username": "integration.payroll", "password": "••••••••", "tenantCode": "ACME" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LoginResponse" }, "meta": { "$ref": "#/components/schemas/Meta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, "example": { "data": { "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…", "refreshToken": "rt_9f3c1a…", "expiresIn": 3600, "session": { "user": { "id": "f0b1c2d3-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "username": "integration.payroll", "email": "integration@acme.example", "displayName": "Payroll integration", "locale": "en", "timeZone": "UTC" }, "tenant": { "id": "c7d8e9f0-1a2b-4c3d-8e4f-5a6b7c8d9e0f", "tenantNumber": "T-0042", "displayName": "Acme Hospitality", "countryCode": "US", "baseCurrency": "USD", "timeZone": "America/New_York", "enabledModules": [ "EMPLOYEE_MASTER", "ATTENDANCE_TIME", "LEAVE", "PAYROLL" ] }, "activeRoleContextId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e", "permissions": [ "PAY_GL:VIEW", "PAY_GL:EXPORT", "PAY_AMOUNT:VIEW" ] } }, "meta": { "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-18T09:15:02.118Z" } } } } }, "401": { "$ref": "#/components/responses/E401" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/auth/refresh": { "post": { "tags": [ "Authentication" ], "operationId": "refreshToken", "summary": "Refresh the access token", "description": "Exchanges a refresh token for a new access token and refresh token. Each refresh token works once; keep the new one. Limited to 20 attempts per minute per client address.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "refreshToken" ], "properties": { "refreshToken": { "type": "string", "minLength": 10, "maxLength": 1000 } } }, "example": { "refreshToken": "rt_9f3c1a…" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LoginResponse" }, "meta": { "$ref": "#/components/schemas/Meta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/auth/logout": { "post": { "tags": [ "Authentication" ], "operationId": "logout", "summary": "Sign out", "description": "Revokes the given refresh token (or the caller's tokens). The access token stays valid until it expires.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "refreshToken": { "type": "string" } } }, "example": { "refreshToken": "rt_9f3c1a…" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "meta": { "$ref": "#/components/schemas/Meta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, "example": { "data": { "success": true }, "meta": { "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-18T09:15:02.118Z" } } } } }, "401": { "$ref": "#/components/responses/E401" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/auth/me": { "get": { "tags": [ "Authentication" ], "operationId": "getSession", "summary": "Current session", "description": "Returns the signed-in identity, tenant, role contexts and resolved permission codes. Useful to check what an integration user is allowed to do.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Session" }, "meta": { "$ref": "#/components/schemas/Meta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/employees/directory": { "get": { "tags": [ "Employees" ], "operationId": "listEmployees", "summary": "List employees", "description": "Employees the caller may see, paged, filtered and sorted. Returns directory columns only; identity, pay and bank data are on the record behind their own field security. Requires EMPLOYEE_DIRECTORY:VIEW.", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Matches employee code and names; every word must match.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "An employment status, or CURRENT for everyone still employed.", "schema": { "type": "string" } }, { "name": "legalEntityId", "in": "query", "required": false, "description": "Only this legal entity.", "schema": { "type": "string", "format": "uuid" } }, { "name": "departmentId", "in": "query", "required": false, "description": "Only people currently in this department.", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "description": "Rows per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "sortBy", "in": "query", "required": false, "description": "Sort column.", "schema": { "type": "string", "enum": [ "employeeCode", "name", "status", "joiningDate" ] } }, { "name": "sortDir", "in": "query", "required": false, "description": "Sort direction.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "rows": { "type": "array", "items": { "$ref": "#/components/schemas/DirectoryRow" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" } } }, "meta": { "$ref": "#/components/schemas/Meta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, "example": { "data": { "rows": [ { "id": "3b8f0d6e-91c4-4b1f-8a62-5d0c7e2f4a19", "employeeCode": "EMP-000214", "givenName": "Ana", "familyName": "Santos", "givenNameAr": null, "familyNameAr": null, "photoAttachmentId": null, "status": "ACTIVE_CONFIRMED", "readiness": "ACTIVE", "joiningDate": "2023-03-12T00:00:00.000Z", "exitDate": null, "legalEntityCode": "LE-MAIN", "jobCode": "SUP-RST", "jobTitle": "Restaurant Supervisor", "workingTitle": null, "departmentCode": "OPS", "departmentName": "Operations", "locationCode": "DT", "locationName": "Downtown Branch", "managerPeriodId": "9c2e4f71-0b8a-4d3e-a6f5-17d2c9e0b384", "managerName": "Fatima Hajri" } ], "total": 1, "page": 1, "pageSize": 25 }, "meta": { "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-18T09:15:02.118Z" } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/employees": { "post": { "tags": [ "Employees" ], "operationId": "createEmployee", "summary": "Create an employee (draft)", "description": "Creates one person and one employment period in DRAFT, after a duplicate check. A high-risk duplicate blocks with 409 until a reviewer lists the cleared person IDs in acknowledgedDuplicateIds. Requires EMPLOYMENT_PERIOD:CREATE.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEmployee" }, "example": { "givenName": "Daniel", "familyName": "Cruz", "gender": "MALE", "nationalityCode": "PH", "dateOfBirth": "1994-06-21", "legalEntityId": "a41e7c02-5f3b-4d8e-9c17-6b2d0e8f3a55", "joiningDate": "2026-11-01", "identifiers": [ { "type": "PASSPORT", "value": "P4821937", "expiresOn": "2031-03-02" } ] } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "personId": { "type": "string", "format": "uuid" }, "employmentPeriodId": { "type": "string", "format": "uuid" }, "employeeCode": { "type": "string" }, "duplicates": { "type": "object", "additionalProperties": true } } }, "meta": { "$ref": "#/components/schemas/Meta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, "example": { "data": { "personId": "d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80", "employmentPeriodId": "0a1b2c3d-4e5f-4a6b-9c7d-8e9f0a1b2c3d", "employeeCode": "EMP-000231", "duplicates": { "candidates": [] } }, "meta": { "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-18T09:15:02.118Z" } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/employees/{id}": { "get": { "tags": [ "Employees" ], "operationId": "getEmployee", "summary": "Get an employee", "description": "The employee record with person, identifiers and current assignments, masked to the caller. Requires EMPLOYMENT_PERIOD:VIEW and the record inside your data scope.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Employment-period ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Employee" }, "meta": { "$ref": "#/components/schemas/Meta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, "example": { "data": { "id": "3b8f0d6e-91c4-4b1f-8a62-5d0c7e2f4a19", "employeeCode": "EMP-000214", "status": "ACTIVE_CONFIRMED", "readiness": "ACTIVE", "joiningDate": "2023-03-12T00:00:00.000Z", "exitDate": null, "legalEntity": { "id": "a41e7c02-5f3b-4d8e-9c17-6b2d0e8f3a55", "code": "LE-MAIN" }, "person": { "id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b", "personCode": "PER-000198", "givenName": "Ana", "familyName": "Santos", "givenNameAr": null, "familyNameAr": null, "dateOfBirth": null, "nationalityCode": null, "identifiers": [ { "id": "aa11bb22-cc33-4d44-8e55-ff6677889900", "identifierType": "PASSPORT", "displayValue": "••••••", "expiresOn": "2031-03-02T00:00:00.000Z", "verificationStatus": "DOCUMENT_VERIFIED" } ] }, "assignments": [ { "id": "1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b", "code": "ASG-000214", "kind": "PRIMARY", "current": { "workingTitle": null, "effectiveFrom": "2026-01-01T00:00:00.000Z" } } ] }, "meta": { "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-18T09:15:02.118Z" } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/employees/{id}/facts/{factKey}": { "get": { "tags": [ "Employees" ], "operationId": "listEmployeeFacts", "summary": "Read an employee fact", "description": "The values of one dated fact (documents, contacts, addresses, contracts, compensation, bank details, dependents, qualifications, entitlements, personal details) as they stood on a date. Each fact has its own permission (for example EMPLOYEE_DOCUMENT:VIEW), and sensitive fields are masked without the matching grant.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Employment-period ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "factKey", "in": "path", "required": true, "description": "The fact to read. GET /employees/metadata/facts lists every fact and its fields.", "schema": { "type": "string", "enum": [ "personal-details", "contacts", "addresses", "documents", "contracts", "compensation", "bank-details", "dependents", "qualifications", "entitlements", "sponsorship" ] } }, { "name": "asOf", "in": "query", "required": false, "description": "Business date; defaults to today.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "meta": { "$ref": "#/components/schemas/Meta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, "example": { "data": [ { "id": "7c8d9e0f-1a2b-4c3d-9e4f-5a6b7c8d9e0f", "documentType": "PASSPORT", "documentNumber": "••••••", "issuingCountryCode": "PH", "issuingAuthority": "Department of Foreign Affairs", "issueDate": "2021-03-02T00:00:00.000Z", "expiryDate": "2031-03-02T00:00:00.000Z", "documentStatus": "ISSUED" } ], "meta": { "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-18T09:15:02.118Z" } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/employees/metadata/facts": { "get": { "tags": [ "Employees" ], "operationId": "listFactDefinitions", "summary": "List fact definitions", "description": "Every declared employee fact with its labels and fields, derived from the schema the server validates against. Requires EMPLOYMENT_PERIOD:VIEW.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "businessObject": { "type": "string" }, "owner": { "type": "string" }, "group": { "type": [ "string", "null" ] }, "singular": { "type": "string" }, "plural": { "type": "string" }, "collection": { "type": "boolean" }, "sensitiveDomain": { "type": [ "string", "null" ] }, "fields": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true } }, "meta": { "$ref": "#/components/schemas/Meta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/config/{entity}": { "get": { "tags": [ "Organization" ], "operationId": "listOrganizationRecords", "summary": "List organization records", "description": "Lists effective-dated configuration records: legal entities, departments, locations, positions, jobs, grades, cost centers, leave types, shifts and more. Requires VIEW on the entity (for example DEPARTMENT:VIEW).", "parameters": [ { "name": "entity", "in": "path", "required": true, "description": "The record type.", "schema": { "type": "string", "enum": [ "legal-entities", "companies", "business-units", "departments", "locations", "organization-nodes", "positions", "jobs", "job-families", "grades", "cost-centers", "employment-types", "employee-categories", "leave-types", "holiday-calendars", "shifts", "document-types" ] } }, { "name": "page", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "description": "Rows per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 25 } }, { "name": "search", "in": "query", "required": false, "description": "Free-text search on code and name.", "schema": { "type": "string" } }, { "name": "sortBy", "in": "query", "required": false, "description": "Sort column.", "schema": { "type": "string" } }, { "name": "sortDir", "in": "query", "required": false, "description": "Sort direction.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } }, { "name": "asOfDate", "in": "query", "required": false, "description": "Return the versions in effect on this date.", "schema": { "type": "string", "format": "date" } }, { "name": "status", "in": "query", "required": false, "description": "Record status filter.", "schema": { "type": "string", "enum": [ "DRAFT", "PENDING", "ACTIVE", "INACTIVE", "ARCHIVED" ] } }, { "name": "activationStatus", "in": "query", "required": false, "description": "Activation status filter.", "schema": { "type": "string", "enum": [ "PENDING", "SCHEDULED", "ACTIVE", "EXPIRED", "SUPERSEDED", "CANCELLED" ] } }, { "name": "companyId", "in": "query", "required": false, "description": "Only this company.", "schema": { "type": "string", "format": "uuid" } }, { "name": "legalEntityId", "in": "query", "required": false, "description": "Only this legal entity.", "schema": { "type": "string", "format": "uuid" } }, { "name": "departmentId", "in": "query", "required": false, "description": "Only this department.", "schema": { "type": "string", "format": "uuid" } }, { "name": "locationId", "in": "query", "required": false, "description": "Only this location.", "schema": { "type": "string", "format": "uuid" } }, { "name": "costCenterId", "in": "query", "required": false, "description": "Only this cost center.", "schema": { "type": "string", "format": "uuid" } }, { "name": "includeInactive", "in": "query", "required": false, "description": "Include inactive records.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/MasterPage" }, "meta": { "$ref": "#/components/schemas/Meta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, "example": { "data": { "items": [ { "id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "recordId": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "code": "OPS", "displayName": "Operations", "recordStatus": "ACTIVE", "versionNo": 2, "effectiveFrom": "2026-01-01", "effectiveTo": null, "approvalStatus": "APPROVED", "activationStatus": "ACTIVE", "isCurrent": true, "rowVersion": 3 } ], "page": 1, "pageSize": 25, "total": 1, "totalPages": 1, "sortDir": "asc" }, "meta": { "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-18T09:15:02.118Z" } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/config/{entity}/{id}": { "get": { "tags": [ "Organization" ], "operationId": "getOrganizationRecord", "summary": "Get an organization record", "description": "One configuration record, optionally as of a date or at a specific version. Requires VIEW on the entity.", "parameters": [ { "name": "entity", "in": "path", "required": true, "description": "The record type.", "schema": { "type": "string", "enum": [ "legal-entities", "companies", "business-units", "departments", "locations", "organization-nodes", "positions", "jobs", "job-families", "grades", "cost-centers", "employment-types", "employee-categories", "leave-types", "holiday-calendars", "shifts", "document-types" ] } }, { "name": "id", "in": "path", "required": true, "description": "Record ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "asOfDate", "in": "query", "required": false, "description": "Version in effect on this date.", "schema": { "type": "string", "format": "date" } }, { "name": "versionId", "in": "query", "required": false, "description": "A specific version.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/MasterRecord" }, "meta": { "$ref": "#/components/schemas/Meta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/attendance/punches/batch": { "post": { "tags": [ "Attendance" ], "operationId": "ingestPunches", "summary": "Send punches (any device)", "description": "The universal ingestion endpoint for biometric terminals, card readers, kiosks and middleware: up to 5,000 events per batch. Idempotent on idempotencyKey, so a device that retries after a timeout never double-punches anyone. Unknown badges, implausible times and replays are kept as visible exceptions rather than dropped. Requires RAW_PUNCH:IMPORT.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PunchBatch" }, "example": { "deviceCode": "DT-GATE-01", "channel": "BIOMETRIC_DEVICE", "idempotencyKey": "DT-GATE-01-20261018-0007", "events": [ { "sourceIdentity": "10482", "eventAt": "2026-10-18T06:52:11-04:00", "direction": "IN", "payload": { "verifyMode": "FINGER", "workCode": 0 } }, { "sourceIdentity": "10517", "eventAt": "2026-10-18T06:55:40-04:00", "direction": "IN" } ] } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/IngestResult" }, "meta": { "$ref": "#/components/schemas/Meta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, "example": { "data": { "batchId": "8d9e0f1a-2b3c-4d4e-9f5a-6b7c8d9e0f1a", "replayed": false, "eventCount": 2, "accepted": 2, "duplicates": 0, "unmatched": 0, "quarantined": 0, "rejected": 0 }, "meta": { "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-18T09:15:02.118Z" } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/attendance/punches": { "get": { "tags": [ "Attendance" ], "operationId": "listPunches", "summary": "Read the punch ledger", "description": "Every captured event and its outcome, newest first, scoped to the people the caller may see. Requires RAW_PUNCH:VIEW.", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Events at or after this instant.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "Events at or before this instant.", "schema": { "type": "string", "format": "date-time" } }, { "name": "employmentPeriodId", "in": "query", "required": false, "description": "Only this employee.", "schema": { "type": "string", "format": "uuid" } }, { "name": "outcome", "in": "query", "required": false, "description": "Only this outcome.", "schema": { "$ref": "#/components/schemas/IngestionOutcome" } }, { "name": "channel", "in": "query", "required": false, "description": "Only this channel.", "schema": { "$ref": "#/components/schemas/CaptureChannel" } }, { "name": "supervisorOnly", "in": "query", "required": false, "description": "Only supervisor entries.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum rows.", "schema": { "type": "integer", "default": 200, "maximum": 500 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RawPunch" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, "example": { "data": [ { "id": "4a5b6c7d-8e9f-4a0b-9c1d-2e3f4a5b6c7d", "batchId": "8d9e0f1a-2b3c-4d4e-9f5a-6b7c8d9e0f1a", "deviceId": "6c7d8e9f-0a1b-4c2d-8e3f-4a5b6c7d8e9f", "channel": "BIOMETRIC_DEVICE", "sourceIdentity": "10482", "employmentPeriodId": "3b8f0d6e-91c4-4b1f-8a62-5d0c7e2f4a19", "eventAt": "2026-10-18T10:52:11.000Z", "receivedAt": "2026-10-18T10:52:14.302Z", "direction": "IN", "latitude": null, "longitude": null, "accuracyMetres": null, "withinGeoFence": null, "outcome": "ACCEPTED", "outcomeReason": null, "duplicateOfId": null, "supervisorEntry": false, "device": { "code": "DT-GATE-01", "name": "Downtown main gate" } } ], "meta": { "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-18T09:15:02.118Z" } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/attendance/punches/exceptions": { "get": { "tags": [ "Attendance" ], "operationId": "listPunchExceptions", "summary": "Punches that need attention", "description": "The latest 100 events that could not become a punch (unmatched identity, quarantined or rejected) with the reason. Requires RAW_PUNCH:VIEW.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RawPunch" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/attendance/devices/silent": { "get": { "tags": [ "Attendance" ], "operationId": "listSilentDevices", "summary": "Devices that have gone quiet", "description": "Active capture devices with no heartbeat within the window (default 6 hours). A silent device makes it look as if nobody came to work. Requires CAPTURE_DEVICE:VIEW.", "parameters": [ { "name": "minutes", "in": "query", "required": false, "description": "Silence threshold in minutes.", "schema": { "type": "integer", "default": 360 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "lastHeartbeatAt": { "type": [ "string", "null" ], "format": "date-time" } } } }, "meta": { "$ref": "#/components/schemas/Meta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, "example": { "data": [ { "id": "6c7d8e9f-0a1b-4c2d-8e3f-4a5b6c7d8e9f", "code": "WH-DOCK-02", "name": "Warehouse dock reader", "lastHeartbeatAt": "2026-10-17T22:04:51.000Z" } ], "meta": { "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-18T09:15:02.118Z" } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/attendance/days": { "get": { "tags": [ "Attendance" ], "operationId": "listAttendanceDays", "summary": "Daily attendance", "description": "Derived daily attendance for a date window: status, scheduled and worked minutes, lateness, overtime and punch pairs. Scoped to the people the caller may see. Requires ATTENDANCE_DAY:VIEW.", "parameters": [ { "name": "from", "in": "query", "required": true, "description": "First business date.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "description": "Last business date.", "schema": { "type": "string", "format": "date" } }, { "name": "employmentPeriodId", "in": "query", "required": false, "description": "Only this employee.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AttendanceDay" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/leave/types/available": { "get": { "tags": [ "Leave" ], "operationId": "listAvailableLeaveTypes", "summary": "Leave types for a person", "description": "The leave types a person may apply for on a date, with their rules (paid, half days, notice, attachments). Requires LEAVE_REQUEST:VIEW.", "parameters": [ { "name": "employmentPeriodId", "in": "query", "required": true, "description": "The employee.", "schema": { "type": "string", "format": "uuid" } }, { "name": "asOf", "in": "query", "required": false, "description": "Business date; defaults to today.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LeaveType" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, "example": { "data": [ { "leaveTypeId": "9e0f1a2b-3c4d-4e5f-8a6b-7c8d9e0f1a2b", "code": "ANNUAL", "name": "Annual leave", "nameAr": "إجازة سنوية", "category": "ANNUAL", "color": "#2563EB", "paid": true, "payPercent": 100, "annualEntitlementDays": 21, "allowHalfDay": true, "countCalendarDays": false, "minNoticeDays": 7, "maxConsecutiveDays": null, "attachmentAfterDays": null, "allowNegative": false, "allowHourly": false, "caseProfile": null, "retroWindowDays": 30 } ], "meta": { "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-18T09:15:02.118Z" } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/leave/balances": { "get": { "tags": [ "Leave" ], "operationId": "getLeaveBalances", "summary": "Leave balances for a person", "description": "One person's balances for a leave year, computed from the ledger: carried, entitled, earned, taken, pending and available. Requires LEAVE_BALANCE:VIEW.", "parameters": [ { "name": "employmentPeriodId", "in": "query", "required": true, "description": "The employee.", "schema": { "type": "string", "format": "uuid" } }, { "name": "year", "in": "query", "required": false, "description": "Leave year; defaults to the current year.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LeaveBalance" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, "example": { "data": [ { "balanceId": "bal-2026-annual", "leaveTypeId": "9e0f1a2b-3c4d-4e5f-8a6b-7c8d9e0f1a2b", "code": "ANNUAL", "name": "Annual leave", "nameAr": "إجازة سنوية", "category": "ANNUAL", "color": "#2563EB", "year": 2026, "asOf": "2026-10-18", "unlimited": false, "carried": 4, "entitled": 21, "earned": 17.5, "adjusted": 0, "expired": 0, "taken": 4, "pending": 3, "balance": 17.5, "available": 14.5 } ], "meta": { "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-18T09:15:02.118Z" } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/leave/requests": { "get": { "tags": [ "Leave" ], "operationId": "listLeaveRequests", "summary": "List leave requests", "description": "Leave requests in the caller's scope, newest first (up to 500). Requires LEAVE_REQUEST:VIEW.", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Comma-separated statuses, e.g. SUBMITTED,APPROVED.", "schema": { "type": "string" } }, { "name": "mine", "in": "query", "required": false, "description": "Only the caller's own requests.", "schema": { "type": "boolean" } }, { "name": "from", "in": "query", "required": false, "description": "Requests ending on or after this date.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Requests starting on or before this date.", "schema": { "type": "string", "format": "date" } }, { "name": "employmentPeriodId", "in": "query", "required": false, "description": "Only this employee.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LeaveRequest" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, "example": { "data": [ { "id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "reference": "LV-2026-00412", "employmentPeriodId": "3b8f0d6e-91c4-4b1f-8a62-5d0c7e2f4a19", "employeeCode": "EMP-000214", "employeeName": "Ana Santos", "leaveTypeId": "9e0f1a2b-3c4d-4e5f-8a6b-7c8d9e0f1a2b", "leaveTypeCode": "ANNUAL", "leaveTypeName": "Annual leave", "category": "ANNUAL", "fromDate": "2026-11-01", "toDate": "2026-11-12", "startHalf": false, "endHalf": false, "days": 10, "status": "SUBMITTED", "phase": "PENDING", "reasonDetail": "Family visit", "submittedAt": "2026-10-18T08:12:00.000Z", "decidedAt": null, "decisionComments": null, "createdAt": "2026-10-18T08:10:31.000Z" } ], "meta": { "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-18T09:15:02.118Z" } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" } } }, "post": { "tags": [ "Leave" ], "operationId": "createLeaveRequest", "summary": "Raise a leave request (draft)", "description": "Creates a leave request as a DRAFT after applying every leave rule; blocking rules return 422 naming the field. Send it for approval with POST /leave/requests/{id}/submit. Requires LEAVE_REQUEST:CREATE.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaveApplication" }, "example": { "employmentPeriodId": "3b8f0d6e-91c4-4b1f-8a62-5d0c7e2f4a19", "leaveTypeId": "9e0f1a2b-3c4d-4e5f-8a6b-7c8d9e0f1a2b", "fromDate": "2026-11-01", "toDate": "2026-11-12", "reasonDetail": "Family visit", "contactDuringLeave": "+1 555 0142" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "reference": { "type": "string" }, "status": { "$ref": "#/components/schemas/LeaveRequestStatus" }, "days": { "type": "number" }, "attachmentRequired": { "type": "boolean" }, "delegateWarnings": { "type": "array", "items": { "type": "string" } } } }, "meta": { "$ref": "#/components/schemas/Meta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, "example": { "data": { "id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "reference": "LV-2026-00412", "status": "DRAFT", "days": 10, "attachmentRequired": false, "delegateWarnings": [] }, "meta": { "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-18T09:15:02.118Z" } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/leave/requests/{id}": { "get": { "tags": [ "Leave" ], "operationId": "getLeaveRequest", "summary": "Get a leave request", "description": "One request with its day-by-day breakdown and ledger entries. Requires LEAVE_REQUEST:VIEW.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Leave request ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LeaveRequest" }, "meta": { "$ref": "#/components/schemas/Meta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/leave/requests/{id}/submit": { "post": { "tags": [ "Leave" ], "operationId": "submitLeaveRequest", "summary": "Submit a leave request", "description": "Sends a draft (or a request returned for information) into the approval workflow. Requires LEAVE_REQUEST:SUBMIT.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Leave request ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "reference": { "type": "string" }, "status": { "$ref": "#/components/schemas/LeaveRequestStatus" }, "exceptions": { "type": "array", "items": { "type": "string" } } } }, "meta": { "$ref": "#/components/schemas/Meta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, "example": { "data": { "id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "reference": "LV-2026-00412", "status": "SUBMITTED", "exceptions": [] }, "meta": { "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-18T09:15:02.118Z" } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/payroll/runs": { "get": { "tags": [ "Payroll" ], "operationId": "listPayrollRuns", "summary": "List payroll runs", "description": "Payroll runs, newest first, with totals (masked without amount access). Requires PAY_RUN:VIEW.", "parameters": [ { "name": "payGroupId", "in": "query", "required": false, "description": "Only this pay group.", "schema": { "type": "string", "format": "uuid" } }, { "name": "periodId", "in": "query", "required": false, "description": "Only this period.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Only this status.", "schema": { "$ref": "#/components/schemas/PayRunStatus" } }, { "name": "runType", "in": "query", "required": false, "description": "Only this run type.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PayRun" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, "example": { "data": [ { "id": "3d4e5f6a-7b8c-4d9e-8f0a-1b2c3d4e5f6a", "reference": "PR-2026-10-MONTHLY", "runType": "REGULAR", "status": "LOCKED", "population": "ALL", "payGroup": { "id": "4e5f6a7b-8c9d-4e0f-9a1b-2c3d4e5f6a7b", "code": "MONTHLY", "name": "Monthly staff" }, "period": { "id": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c", "code": "2026-10", "label": "October 2026", "start": "2026-10-01", "end": "2026-10-31", "payDate": "2026-10-28", "status": "OPEN" }, "paymentDate": "2026-10-28", "headcount": 214, "totals": { "gross": "352910.00", "deductions": "10555.00", "net": "342355.00", "employerContrib": "0.00", "masked": false }, "exceptionCounts": { "ERROR": 0, "WARNING": 3, "INFO": 12, "unacknowledged": 0 }, "calculatedAt": "2026-10-24T09:02:11.000Z", "approvedAt": "2026-10-25T13:40:00.000Z", "lockedAt": "2026-10-25T14:05:12.000Z", "publishedAt": null, "resultHash": "c1f0…9a", "rowVersion": 7, "createdAt": "2026-10-20T07:00:00.000Z" } ], "meta": { "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-18T09:15:02.118Z" } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/payroll/runs/{id}": { "get": { "tags": [ "Payroll" ], "operationId": "getPayrollRun", "summary": "Get a payroll run", "description": "A run with totals, the people who made and approved it, and its status timeline. Requires PAY_RUN:VIEW.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Payroll run ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PayRun" }, "meta": { "$ref": "#/components/schemas/Meta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/payroll/journals": { "get": { "tags": [ "Payroll" ], "operationId": "listJournals", "summary": "List GL journals", "description": "Accrual, payment, provision, reversal and settlement journals produced by locked payroll runs, newest first. Superseded versions are hidden unless asked for. Requires PAY_GL:VIEW.", "parameters": [ { "name": "runId", "in": "query", "required": false, "description": "Only this run.", "schema": { "type": "string", "format": "uuid" } }, { "name": "periodId", "in": "query", "required": false, "description": "Only this period.", "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "query", "required": false, "description": "Only this kind.", "schema": { "$ref": "#/components/schemas/JournalKind" } }, { "name": "status", "in": "query", "required": false, "description": "Only this status.", "schema": { "$ref": "#/components/schemas/JournalStatus" } }, { "name": "includeSuperseded", "in": "query", "required": false, "description": "Include superseded versions.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Journal" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, "example": { "data": [ { "id": "6a7b8c9d-0e1f-4a2b-9c3d-4e5f6a7b8c9d", "reference": "JRN-2026-10-ACC-01", "kind": "ACCRUAL", "kindLabel": "Accrual", "status": "BALANCED", "versionNo": 1, "runId": "3d4e5f6a-7b8c-4d9e-8f0a-1b2c3d4e5f6a", "runReference": "PR-2026-10-MONTHLY", "periodId": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c", "periodCode": "2026-10", "legalEntityId": "a41e7c02-5f3b-4d8e-9c17-6b2d0e8f3a55", "legalEntityCode": "LE-MAIN", "legalEntityName": "Acme Hospitality Inc.", "postingDate": "2026-10-31", "currency": "USD", "aggregation": "ACCOUNT_COSTCENTRE", "totalDebit": "352910.00", "totalCredit": "352910.00", "masked": false, "exportable": true, "lineCount": 48, "exportCount": 0, "lastExportedAt": null, "createdAt": "2026-10-25T14:05:20.000Z", "rowVersion": 1 } ], "meta": { "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-18T09:15:02.118Z" } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/payroll/journals/{id}": { "get": { "tags": [ "Payroll" ], "operationId": "getJournal", "summary": "Get a GL journal", "description": "A journal with its lines (account, cost centre, department, analysis, debit, credit), diagnostics, previous exports and versions. Requires PAY_GL:VIEW.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Journal ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/JournalDetail" }, "meta": { "$ref": "#/components/schemas/Meta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/payroll/journals/{id}/export": { "post": { "tags": [ "Payroll" ], "operationId": "exportJournal", "summary": "Export a journal for your ERP", "description": "Renders a balanced journal through a journal layout (configurable columns, date format and file type) as CSV or XLSX, ready to import into your ERP or accounting system. Each export is a new, logged version with a SHA-256. Requires PAY_GL:EXPORT and PAY_AMOUNT:VIEW.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Journal ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "layoutCode": { "type": "string", "maxLength": 40, "description": "Journal layout to use; defaults to the tenant's default layout." }, "format": { "type": "string", "enum": [ "CSV", "XLSX" ], "description": "Defaults to the layout's format." }, "reason": { "type": "string", "maxLength": 500, "description": "Recorded in the audit trail." } } }, "example": { "layoutCode": "GENERIC_CSV", "format": "CSV", "reason": "October close" } } } }, "responses": { "201": { "description": "The journal file (not wrapped in the JSON envelope).", "headers": { "Content-Disposition": { "schema": { "type": "string" }, "description": "attachment; filename=\"…\"" } }, "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } }, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/payroll/journals/{id}/exports/{exportId}": { "get": { "tags": [ "Payroll" ], "operationId": "downloadJournalExport", "summary": "Download a stored export", "description": "Downloads an earlier export version again, byte for byte. The download is logged. Requires PAY_GL:EXPORT.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Journal ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "exportId", "in": "path", "required": true, "description": "Export version ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The stored journal file.", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } }, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/payroll/payslips/{id}": { "get": { "tags": [ "Payroll" ], "operationId": "getPayslip", "summary": "Get a payslip", "description": "One payslip as printable HTML with its SHA-256. Available to payroll users with amount access (audited) or to the employee for their own published payslip; anyone else gets 404. Requires PAY_RUN:VIEW or PAY_PAYSLIP:VIEW.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Payslip ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PayslipDocument" }, "meta": { "$ref": "#/components/schemas/Meta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/payroll/me/payslips": { "get": { "tags": [ "Payroll" ], "operationId": "listMyPayslips", "summary": "My payslips", "description": "The caller's own published payslips, newest first. Never takes an employee ID: the employee comes from the login. Requires PAY_PAYSLIP:VIEW.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MyPayslip" } }, "meta": { "$ref": "#/components/schemas/Meta" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, "example": { "data": [ { "id": "7b8c9d0e-1f2a-4b3c-8d4e-5f6a7b8c9d0e", "periodCode": "2026-09", "periodLabel": "September 2026", "periodLabelAr": "سبتمبر 2026", "payDate": "2026-09-28", "net": "1715.00", "currency": "USD", "versionNo": 1, "revised": false, "publishedAt": "2026-09-27T12:00:00.000Z" } ], "meta": { "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-18T09:15:02.118Z" } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/ext/me": { "get": { "tags": [ "External API" ], "operationId": "extMe", "security": [ { "apiKeyAuth": [] } ], "summary": "The key itself", "description": "The workspace the key belongs to, its name, prefix, granted scopes and expiry, and the scopes in effect right now. No scope needed.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "tenant": { "type": [ "string", "null" ] }, "key": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "effectiveScopes": { "type": "array", "items": { "type": "string" } } } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "tenant": "ACME-RETAIL", "key": { "name": "Payroll bureau sync", "prefix": "mk_live_7Hq2", "scopes": [ "EMPLOYMENT_PERIOD:VIEW", "PAY_RUN:VIEW" ], "expiresAt": "2027-04-18T09:00:00.000Z" }, "effectiveScopes": [ "EMPLOYMENT_PERIOD:VIEW", "PAY_RUN:VIEW" ] }, "meta": { "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-20T09:15:02.118Z" } } } } }, "401": { "$ref": "#/components/responses/X401" }, "429": { "$ref": "#/components/responses/X429" } } } }, "/ext/employees": { "get": { "tags": [ "External API" ], "operationId": "extEmployees", "security": [ { "apiKeyAuth": [] } ], "summary": "List employees", "description": "Employment records, cursor-paged in id order. Pass `nextCursor` back as `cursor` until it is null. Scope: `EMPLOYMENT_PERIOD:VIEW`. The key's effective permissions are its scopes intersected with its creator's live permissions, and rows are limited to the creator's data scope.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–500 (default 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "The nextCursor of the previous page.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Only this employment status.", "schema": { "$ref": "#/components/schemas/EmploymentStatus" } }, { "name": "updatedSince", "in": "query", "required": false, "description": "Only records changed at or after this instant (ISO 8601 with offset).", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExtEmployee" } }, "nextCursor": { "type": [ "string", "null" ], "format": "uuid" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "id": "3f2a9c10-6b1e-4d7a-9c2e-5a8b7d6c4e21", "employeeCode": "EMP-000214", "personId": "0b7e3c55-1f9a-4c2d-8e6b-3a4d5c6e7f80", "givenName": "Ana", "middleName": null, "familyName": "Santos", "preferredName": null, "givenNameAr": null, "familyNameAr": null, "nationality": "PH", "email": "ana.santos@example.com", "status": "ACTIVE_CONFIRMED", "legalEntityId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "joiningDate": "2023-03-12", "originalJoiningDate": "2023-03-12", "exitDate": null, "updatedAt": "2026-10-19T14:02:11.000Z" } ], "nextCursor": null, "meta": { "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-20T09:15:02.118Z" } } } } }, "401": { "$ref": "#/components/responses/X401" }, "403": { "$ref": "#/components/responses/X403" }, "422": { "$ref": "#/components/responses/X422" }, "429": { "$ref": "#/components/responses/X429" } } } }, "/ext/employees/{id}": { "get": { "tags": [ "External API" ], "operationId": "extEmployee", "security": [ { "apiKeyAuth": [] } ], "summary": "One employee", "description": "One employment record by id. Scope: `EMPLOYMENT_PERIOD:VIEW`. The key's effective permissions are its scopes intersected with its creator's live permissions, and rows are limited to the creator's data scope.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Employment record id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ExtEmployee" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": { "id": "3f2a9c10-6b1e-4d7a-9c2e-5a8b7d6c4e21", "employeeCode": "EMP-000214", "personId": "0b7e3c55-1f9a-4c2d-8e6b-3a4d5c6e7f80", "givenName": "Ana", "middleName": null, "familyName": "Santos", "preferredName": null, "givenNameAr": null, "familyNameAr": null, "nationality": "PH", "email": "ana.santos@example.com", "status": "ACTIVE_CONFIRMED", "legalEntityId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "joiningDate": "2023-03-12", "originalJoiningDate": "2023-03-12", "exitDate": null, "updatedAt": "2026-10-19T14:02:11.000Z" }, "meta": { "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-20T09:15:02.118Z" } } } } }, "401": { "$ref": "#/components/responses/X401" }, "403": { "$ref": "#/components/responses/X403" }, "404": { "$ref": "#/components/responses/X404" }, "429": { "$ref": "#/components/responses/X429" } } } }, "/ext/attendance/punches": { "get": { "tags": [ "External API" ], "operationId": "extPunches", "security": [ { "apiKeyAuth": [] } ], "summary": "Read raw punches", "description": "The capture ledger: every punch received, from any channel. Scope: `RAW_PUNCH:VIEW`. The key's effective permissions are its scopes intersected with its creator's live permissions, and rows are limited to the creator's data scope.", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "From this instant (ISO 8601 with offset).", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "Up to this instant (ISO 8601 with offset).", "schema": { "type": "string", "format": "date-time" } }, { "name": "employeeId", "in": "query", "required": false, "description": "One employee only.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "1–500 (default 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExtPunch" } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "id": "5c4b3a29-1807-4f6e-9d5c-4b3a29180716", "employeeId": "3f2a9c10-6b1e-4d7a-9c2e-5a8b7d6c4e21", "employeeCode": "EMP-000214", "sourceIdentity": "10482", "eventAt": "2026-10-20T06:52:11.000Z", "receivedAt": "2026-10-20T06:52:14.380Z", "direction": "IN", "channel": "API", "device": "DT-GATE-01", "outcome": "ACCEPTED" } ], "meta": { "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-20T09:15:02.118Z" } } } } }, "401": { "$ref": "#/components/responses/X401" }, "403": { "$ref": "#/components/responses/X403" }, "422": { "$ref": "#/components/responses/X422" }, "429": { "$ref": "#/components/responses/X429" } } } }, "/ext/attendance/punches/batch": { "post": { "tags": [ "External API" ], "operationId": "extIngestPunches", "security": [ { "apiKeyAuth": [] } ], "summary": "Send punches (batch)", "description": "The same ingestion as `POST /attendance/punches/batch`, authenticated with an API key and recorded on the API channel. Idempotent on `idempotencyKey`: re-sending a batch returns the original result. Scope: `RAW_PUNCH:IMPORT`. The key's effective permissions are its scopes intersected with its creator's live permissions, and rows are limited to the creator's data scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "idempotencyKey", "events" ], "properties": { "idempotencyKey": { "type": "string", "description": "Unique per batch; a retry sends the same value." }, "deviceCode": { "type": "string", "description": "Optional device code registered in Mawro." }, "events": { "type": "array", "items": { "type": "object", "required": [ "sourceIdentity", "eventAt" ], "properties": { "sourceIdentity": { "type": "string" }, "eventAt": { "type": "string", "format": "date-time" }, "direction": { "type": "string", "enum": [ "IN", "OUT" ] } } } } } }, "example": { "idempotencyKey": "tms-export-20261020-0912", "deviceCode": "DT-GATE-01", "events": [ { "sourceIdentity": "10482", "eventAt": "2026-10-20T06:52:11Z", "direction": "IN" } ] } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/paths/~1attendance~1punches~1batch/post/responses/201/content/application~1json/schema" }, "example": { "data": { "batchId": "8d9e0f1a-2b3c-4d4e-9f5a-6b7c8d9e0f1a", "replayed": false, "eventCount": 1, "accepted": 1, "duplicates": 0, "unmatched": 0, "quarantined": 0, "rejected": 0 }, "meta": { "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-20T09:15:02.118Z" } } } } }, "401": { "$ref": "#/components/responses/X401" }, "403": { "$ref": "#/components/responses/X403" }, "422": { "$ref": "#/components/responses/X422" }, "429": { "$ref": "#/components/responses/X429" } } } }, "/ext/leave/balances": { "get": { "tags": [ "External API" ], "operationId": "extLeaveBalances", "security": [ { "apiKeyAuth": [] } ], "summary": "Leave balances", "description": "Balances for one year, per employee and leave type. Scope: `LEAVE_BALANCE:VIEW`. The key's effective permissions are its scopes intersected with its creator's live permissions, and rows are limited to the creator's data scope.", "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Calendar year (default: the current year).", "schema": { "type": "integer", "minimum": 2000, "maximum": 2100 } }, { "name": "employeeId", "in": "query", "required": false, "description": "One employee only.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "1–2000 (default 1000).", "schema": { "type": "integer", "minimum": 1, "maximum": 2000 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExtLeaveBalance" } }, "year": { "type": "integer" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "year": 2026, "data": [ { "employeeId": "3f2a9c10-6b1e-4d7a-9c2e-5a8b7d6c4e21", "employeeCode": "EMP-000214", "leaveType": "ANNUAL", "leaveTypeName": "Annual Leave", "carried": 0, "entitled": 30, "adjusted": 0, "taken": 9.5, "pending": 2, "available": 18.5, "unlimited": false } ], "meta": { "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-20T09:15:02.118Z" } } } } }, "401": { "$ref": "#/components/responses/X401" }, "403": { "$ref": "#/components/responses/X403" }, "404": { "$ref": "#/components/responses/X404" }, "422": { "$ref": "#/components/responses/X422" }, "429": { "$ref": "#/components/responses/X429" } } } }, "/ext/payroll/runs": { "get": { "tags": [ "External API" ], "operationId": "extPayrollRuns", "security": [ { "apiKeyAuth": [] } ], "summary": "Approved payroll runs", "description": "The latest 100 runs that are approved or later (never a draft). Scope: `PAY_RUN:VIEW`. The key's effective permissions are its scopes intersected with its creator's live permissions, and rows are limited to the creator's data scope.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExtPayRun" } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "data": [ { "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "reference": "RUN-2026-09-01", "runType": "REGULAR", "status": "PAID", "periodId": "b0c1d2e3-f4a5-4b6c-9d8e-7f6a5b4c3d2e", "paymentDate": "2026-09-30", "approvedAt": "2026-09-27T11:20:00.000Z", "publishedAt": "2026-09-28T08:00:00.000Z", "headcount": 412 } ], "meta": { "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-20T09:15:02.118Z" } } } } }, "401": { "$ref": "#/components/responses/X401" }, "403": { "$ref": "#/components/responses/X403" }, "429": { "$ref": "#/components/responses/X429" } } } }, "/ext/payroll/runs/{id}/export": { "get": { "tags": [ "External API" ], "operationId": "extPayrollExport", "security": [ { "apiKeyAuth": [] } ], "summary": "One run’s results", "description": "Results per employee and per pay component. Amounts are included only when the key's creator holds the SALARY sensitive grant (`amountsIncluded` says which). Scope: `PAY_RUN:VIEW`. The key's effective permissions are its scopes intersected with its creator's live permissions, and rows are limited to the creator's data scope.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Payroll run id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExtPayLine" } }, "run": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "reference": { "type": "string" }, "status": { "type": "string" }, "runType": { "type": "string" }, "paymentDate": { "type": [ "string", "null" ], "format": "date" } } }, "amountsIncluded": { "type": "boolean" }, "currency": { "type": "string" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "run": { "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "reference": "RUN-2026-09-01", "status": "PAID", "runType": "REGULAR", "paymentDate": "2026-09-30" }, "amountsIncluded": false, "data": [ { "employeeId": "3f2a9c10-6b1e-4d7a-9c2e-5a8b7d6c4e21", "employeeCode": "EMP-000214", "name": "Ana Santos", "status": "CALCULATED", "costCenter": "CC-DT-FOH", "paymentMethod": "BANK_TRANSFER" } ], "meta": { "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-20T09:15:02.118Z" } } } } }, "401": { "$ref": "#/components/responses/X401" }, "403": { "$ref": "#/components/responses/X403" }, "404": { "$ref": "#/components/responses/X404" }, "429": { "$ref": "#/components/responses/X429" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Access token from POST /auth/login." }, "apiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "mk_live_<40 characters>", "description": "A workspace API key from Settings › Integrations › API keys." } }, "schemas": { "Meta": { "type": "object", "description": "Added to every JSON response. Quote the correlation ID when contacting support; it is also sent as the X-Correlation-Id header.", "properties": { "correlationId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "Message": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "ERROR", "WARNING", "SUCCESS", "INFORMATION" ] }, "text": { "type": "string" }, "field": { "type": "string" } } }, "FieldError": { "type": "object", "required": [ "field", "key", "message", "severity" ], "properties": { "field": { "type": "string" }, "key": { "type": "string", "example": "CFG-001" }, "message": { "type": "string" }, "severity": { "type": "string", "enum": [ "ERROR", "WARNING", "INFORMATION" ] } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "key", "type", "message", "statusCode", "correlationId", "timestamp" ], "properties": { "key": { "type": "string", "description": "Stable message key, e.g. CFG-001 (validation), CFG-008 (permission denied), CFG-009 (outside data scope), CFG-013 (stale version), CFG-038 (not found in your tenant)." }, "type": { "type": "string", "enum": [ "ERROR" ] }, "message": { "type": "string", "description": "A human-readable sentence, safe to show to users." }, "statusCode": { "type": "integer" }, "correlationId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "path": { "type": "string" }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/FieldError" }, "description": "Per-field problems on a 422." }, "currentRowVersion": { "type": "integer", "description": "Present on optimistic-locking conflicts (CFG-013)." } } } } }, "Session": { "type": "object", "description": "The signed-in identity, tenant, role contexts and resolved permissions. Abridged here; additional fields may be present.", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "username": { "type": "string" }, "email": { "type": "string" }, "displayName": { "type": "string" }, "locale": { "type": "string" }, "timeZone": { "type": "string" } } }, "tenant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantNumber": { "type": "string" }, "displayName": { "type": "string" }, "countryCode": { "type": "string" }, "baseCurrency": { "type": "string" }, "timeZone": { "type": "string" }, "enabledModules": { "type": "array", "items": { "type": "string" } } } }, "activeRoleContextId": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permission codes in OBJECT:ACTION form, e.g. RAW_PUNCH:IMPORT." } }, "additionalProperties": true }, "LoginResponse": { "type": "object", "required": [ "accessToken", "refreshToken", "expiresIn", "session" ], "properties": { "accessToken": { "type": "string", "description": "JWT to send as Authorization: Bearer ." }, "refreshToken": { "type": "string" }, "expiresIn": { "type": "integer", "description": "Access-token lifetime in seconds." }, "session": { "$ref": "#/components/schemas/Session" } } }, "EmploymentStatus": { "type": "string", "enum": [ "DRAFT", "PENDING_ACTIVATION", "SCHEDULED_ACTIVE", "ACTIVE_ON_PROBATION", "EXTENDED_PROBATION", "ACTIVE_CONFIRMED", "ON_LEAVE", "UNPAID_LEAVE", "SECONDED", "SUSPENDED", "NOTICE_PERIOD", "ABSCONDED", "EXITED", "RETIRED", "DECEASED", "CANCELLED" ] }, "EmployeeReadiness": { "type": "string", "enum": [ "DRAFT", "PENDING_ACTIVATION", "READY", "SCHEDULED", "ACTIVE", "BLOCKED" ] }, "DirectoryRow": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The employment-period ID: the identifier every other employee endpoint takes." }, "employeeCode": { "type": "string" }, "givenName": { "type": "string" }, "familyName": { "type": "string" }, "givenNameAr": { "type": [ "string", "null" ] }, "familyNameAr": { "type": [ "string", "null" ] }, "photoAttachmentId": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/EmploymentStatus" }, "readiness": { "$ref": "#/components/schemas/EmployeeReadiness" }, "joiningDate": { "type": "string", "format": "date-time" }, "exitDate": { "type": [ "string", "null" ], "format": "date-time" }, "legalEntityCode": { "type": [ "string", "null" ] }, "jobCode": { "type": [ "string", "null" ] }, "jobTitle": { "type": [ "string", "null" ] }, "workingTitle": { "type": [ "string", "null" ] }, "departmentCode": { "type": [ "string", "null" ] }, "departmentName": { "type": [ "string", "null" ] }, "locationCode": { "type": [ "string", "null" ] }, "locationName": { "type": [ "string", "null" ] }, "managerPeriodId": { "type": [ "string", "null" ] }, "managerName": { "type": [ "string", "null" ] } } }, "Employee": { "type": "object", "description": "The employee record, masked to the caller. Date of birth, nationality and identifier numbers are withheld without the IDENTITY grant (unless the record is your own).", "properties": { "id": { "type": "string", "format": "uuid" }, "employeeCode": { "type": "string" }, "status": { "$ref": "#/components/schemas/EmploymentStatus" }, "readiness": { "$ref": "#/components/schemas/EmployeeReadiness" }, "joiningDate": { "type": "string", "format": "date-time" }, "exitDate": { "type": [ "string", "null" ], "format": "date-time" }, "legalEntity": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" } } }, "person": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "personCode": { "type": "string" }, "givenName": { "type": "string" }, "familyName": { "type": "string" }, "givenNameAr": { "type": [ "string", "null" ] }, "familyNameAr": { "type": [ "string", "null" ] }, "dateOfBirth": { "type": [ "string", "null" ], "format": "date-time" }, "nationalityCode": { "type": [ "string", "null" ] }, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "identifierType": { "type": "string" }, "displayValue": { "type": "string" }, "expiresOn": { "type": [ "string", "null" ], "format": "date-time" }, "verificationStatus": { "type": "string" } } } } } }, "assignments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "kind": { "type": "string", "enum": [ "PRIMARY", "SECONDARY", "SECONDMENT", "DEPUTATION" ] }, "current": { "type": [ "object", "null" ], "additionalProperties": true } } } } } }, "CreateEmployee": { "type": "object", "required": [ "givenName", "familyName", "legalEntityId", "joiningDate" ], "properties": { "givenName": { "type": "string" }, "middleName": { "type": [ "string", "null" ] }, "familyName": { "type": "string" }, "givenNameAr": { "type": [ "string", "null" ] }, "familyNameAr": { "type": [ "string", "null" ] }, "dateOfBirth": { "type": [ "string", "null" ], "format": "date" }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE", "UNSPECIFIED" ] }, "nationalityCode": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2." }, "legalEntityId": { "type": "string", "format": "uuid" }, "joiningDate": { "type": "string", "format": "date" }, "identifiers": { "type": "array", "items": { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "type": "string" }, "value": { "type": "string" }, "expiresOn": { "type": [ "string", "null" ], "format": "date" } } } }, "acknowledgedDuplicateIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Person IDs a reviewer has checked and cleared as not duplicates." } } }, "CaptureChannel": { "type": "string", "enum": [ "BIOMETRIC_DEVICE", "CARD_READER", "MOBILE_APP", "WEB", "KIOSK", "SUPERVISOR_ENTRY", "API", "IMPORT" ] }, "IngestionOutcome": { "type": "string", "enum": [ "ACCEPTED", "DUPLICATE", "UNMATCHED_IDENTITY", "QUARANTINED", "REJECTED" ] }, "PunchBatch": { "type": "object", "required": [ "channel", "idempotencyKey", "events" ], "properties": { "deviceCode": { "type": [ "string", "null" ], "maxLength": 60, "description": "Code of a registered capture device. An unknown or decommissioned device is refused (422)." }, "channel": { "$ref": "#/components/schemas/CaptureChannel" }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Unique per delivery. Re-sending the same key returns the first result unchanged (replayed: true) instead of ingesting again." }, "events": { "type": "array", "minItems": 1, "maxItems": 5000, "items": { "type": "object", "required": [ "sourceIdentity", "eventAt" ], "properties": { "sourceIdentity": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The identity the device presented: badge number or device user ID." }, "eventAt": { "type": "string", "maxLength": 60, "description": "When the event happened at the source, ISO 8601 with an offset. An unparseable time is kept and quarantined, not refused." }, "direction": { "type": "string", "enum": [ "IN", "OUT" ], "description": "Omit when the device does not report one; pairing decides." }, "latitude": { "type": [ "number", "null" ], "minimum": -90, "maximum": 90 }, "longitude": { "type": [ "number", "null" ], "minimum": -180, "maximum": 180 }, "accuracyMetres": { "type": [ "number", "null" ], "minimum": 0 }, "payload": { "type": "object", "additionalProperties": true, "description": "The original device record. Hashed and kept so a dispute can be settled against it." } } } } } }, "IngestResult": { "type": "object", "properties": { "batchId": { "type": "string", "format": "uuid" }, "replayed": { "type": "boolean" }, "eventCount": { "type": "integer" }, "accepted": { "type": "integer" }, "duplicates": { "type": "integer" }, "unmatched": { "type": "integer" }, "quarantined": { "type": "integer" }, "rejected": { "type": "integer" } } }, "RawPunch": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "batchId": { "type": [ "string", "null" ] }, "deviceId": { "type": [ "string", "null" ] }, "channel": { "$ref": "#/components/schemas/CaptureChannel" }, "sourceIdentity": { "type": "string" }, "employmentPeriodId": { "type": [ "string", "null" ], "description": "Null when no employee matched (UNMATCHED_IDENTITY)." }, "eventAt": { "type": "string", "format": "date-time" }, "receivedAt": { "type": "string", "format": "date-time" }, "direction": { "type": "string", "enum": [ "IN", "OUT", "AMBIGUOUS" ] }, "latitude": { "type": [ "string", "null" ], "description": "Decimal, serialised as a string." }, "longitude": { "type": [ "string", "null" ] }, "accuracyMetres": { "type": [ "integer", "null" ] }, "withinGeoFence": { "type": [ "boolean", "null" ] }, "outcome": { "$ref": "#/components/schemas/IngestionOutcome" }, "outcomeReason": { "type": [ "string", "null" ] }, "duplicateOfId": { "type": [ "string", "null" ] }, "supervisorEntry": { "type": "boolean" }, "payloadHash": { "type": "string" }, "device": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "name": { "type": "string" } } } } }, "AttendanceDay": { "type": "object", "description": "A derived day. Each day carries its current result (status, worked and late minutes, pairs); additional fields may be present.", "properties": { "id": { "type": "string", "format": "uuid" }, "employmentPeriodId": { "type": "string", "format": "uuid" }, "businessDate": { "type": "string", "format": "date-time" }, "lockState": { "type": "string" }, "employmentPeriod": { "type": "object", "properties": { "employeeCode": { "type": "string" }, "person": { "type": "object", "properties": { "givenName": { "type": "string" }, "familyName": { "type": "string" } } } } }, "results": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "NO_DATA", "PRESENT", "HALF_DAY", "SHORT_HOURS", "LEAVE", "HOLIDAY", "WEEKLY_OFF", "ON_DUTY", "ABSENT" ] }, "dayType": { "type": "string" }, "scheduledStartAt": { "type": [ "string", "null" ], "format": "date-time" }, "scheduledEndAt": { "type": [ "string", "null" ], "format": "date-time" }, "scheduledMinutes": { "type": "integer" }, "workedMinutes": { "type": "integer" }, "lateMinutes": { "type": "integer" }, "earlyMinutes": { "type": "integer" }, "candidateOvertimeMinutes": { "type": "integer" }, "approvedOvertimeMinutes": { "type": "integer" }, "exceptionCount": { "type": "integer" }, "timeZone": { "type": "string" }, "pairs": { "type": "array", "items": { "type": "object", "properties": { "startAt": { "type": "string", "format": "date-time" }, "endAt": { "type": [ "string", "null" ], "format": "date-time" }, "reasonCode": { "type": [ "string", "null" ] } } } } }, "additionalProperties": true } } }, "additionalProperties": true }, "MasterRecord": { "type": "object", "description": "One effective-dated configuration record (current version unless asOfDate is given). Entity-specific fields are included alongside these common ones.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Version ID." }, "recordId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "displayName": { "type": "string" }, "recordStatus": { "type": "string", "enum": [ "DRAFT", "PENDING", "ACTIVE", "INACTIVE", "ARCHIVED" ] }, "versionNo": { "type": "integer" }, "effectiveFrom": { "type": "string", "format": "date" }, "effectiveTo": { "type": [ "string", "null" ], "format": "date" }, "approvalStatus": { "type": "string", "enum": [ "DRAFT", "SUBMITTED", "RETURNED", "REJECTED", "APPROVED" ] }, "activationStatus": { "type": "string", "enum": [ "PENDING", "SCHEDULED", "ACTIVE", "EXPIRED", "SUPERSEDED", "CANCELLED" ] }, "isCurrent": { "type": "boolean" }, "rowVersion": { "type": "integer" } }, "additionalProperties": true }, "MasterPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MasterRecord" } }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" }, "sortBy": { "type": "string" }, "sortDir": { "type": "string", "enum": [ "asc", "desc" ] } } }, "LeaveType": { "type": "object", "properties": { "leaveTypeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": [ "string", "null" ] }, "category": { "type": "string" }, "color": { "type": "string" }, "paid": { "type": "boolean" }, "payPercent": { "type": "number" }, "annualEntitlementDays": { "type": [ "number", "null" ] }, "allowHalfDay": { "type": "boolean" }, "countCalendarDays": { "type": "boolean" }, "minNoticeDays": { "type": [ "integer", "null" ] }, "maxConsecutiveDays": { "type": [ "integer", "null" ] }, "attachmentAfterDays": { "type": [ "integer", "null" ] }, "allowNegative": { "type": "boolean" }, "allowHourly": { "type": "boolean" }, "caseProfile": { "type": [ "string", "null" ] }, "retroWindowDays": { "type": [ "integer", "null" ] } } }, "LeaveBalance": { "type": "object", "properties": { "balanceId": { "type": "string" }, "leaveTypeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": [ "string", "null" ] }, "category": { "type": "string" }, "color": { "type": "string" }, "year": { "type": "integer" }, "asOf": { "type": "string", "format": "date" }, "unlimited": { "type": "boolean" }, "carried": { "type": "number" }, "entitled": { "type": "number" }, "earned": { "type": "number" }, "adjusted": { "type": "number" }, "expired": { "type": "number" }, "taken": { "type": "number" }, "pending": { "type": "number" }, "balance": { "type": "number" }, "available": { "type": "number" } }, "additionalProperties": true }, "LeaveRequestStatus": { "type": "string", "enum": [ "DRAFT", "SUBMITTED", "INFO_REQUESTED", "APPROVED", "REJECTED", "CANCELLED", "WITHDRAWN" ] }, "LeaveRequest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "reference": { "type": "string" }, "employmentPeriodId": { "type": "string", "format": "uuid" }, "employeeCode": { "type": "string" }, "employeeName": { "type": "string" }, "leaveTypeId": { "type": "string", "format": "uuid" }, "leaveTypeCode": { "type": "string" }, "leaveTypeName": { "type": "string" }, "category": { "type": "string" }, "fromDate": { "type": "string", "format": "date" }, "toDate": { "type": "string", "format": "date" }, "startHalf": { "type": "boolean" }, "endHalf": { "type": "boolean" }, "days": { "type": "number" }, "status": { "$ref": "#/components/schemas/LeaveRequestStatus" }, "phase": { "type": "string" }, "reasonDetail": { "type": [ "string", "null" ] }, "submittedAt": { "type": [ "string", "null" ], "format": "date-time" }, "decidedAt": { "type": [ "string", "null" ], "format": "date-time" }, "decisionComments": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "LeaveApplication": { "type": "object", "required": [ "employmentPeriodId", "leaveTypeId", "fromDate" ], "properties": { "employmentPeriodId": { "type": "string", "format": "uuid" }, "leaveTypeId": { "type": "string", "format": "uuid" }, "fromDate": { "type": "string", "format": "date" }, "toDate": { "type": "string", "format": "date", "description": "Defaults to fromDate." }, "startHalf": { "type": "boolean", "description": "First day is a half day." }, "endHalf": { "type": "boolean", "description": "Last day is a half day." }, "hours": { "type": "number", "description": "Hourly leave, in quarter hours (e.g. 2 or 3.5). Not combinable with half days." }, "reasonDetail": { "type": "string", "maxLength": 2000 }, "contactDuringLeave": { "type": "string", "maxLength": 120 }, "handoverNote": { "type": "string", "maxLength": 2000 }, "handoverToId": { "type": "string", "format": "uuid" }, "handoverTasks": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 200 } }, "delegateId": { "type": "string", "format": "uuid", "description": "Who covers your approvals while you are away." }, "delegationComments": { "type": "string" } } }, "JournalStatus": { "type": "string", "enum": [ "DRAFT", "BALANCED", "UNBALANCED", "EXPORTED", "SUPERSEDED" ] }, "JournalKind": { "type": "string", "enum": [ "ACCRUAL", "PAYMENT", "PROVISION", "REVERSAL", "SETTLEMENT" ] }, "Journal": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "reference": { "type": "string" }, "kind": { "$ref": "#/components/schemas/JournalKind" }, "kindLabel": { "type": "string" }, "status": { "$ref": "#/components/schemas/JournalStatus" }, "versionNo": { "type": "integer" }, "runId": { "type": [ "string", "null" ] }, "runReference": { "type": [ "string", "null" ] }, "periodId": { "type": "string" }, "periodCode": { "type": [ "string", "null" ] }, "legalEntityId": { "type": "string" }, "legalEntityCode": { "type": [ "string", "null" ] }, "legalEntityName": { "type": [ "string", "null" ] }, "postingDate": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "aggregation": { "type": "string", "enum": [ "ACCOUNT_COSTCENTRE", "EMPLOYEE" ] }, "totalDebit": { "type": [ "string", "null" ], "description": "Decimal string; null when amounts are masked for the caller." }, "totalCredit": { "type": [ "string", "null" ] }, "masked": { "type": "boolean" }, "exportable": { "type": "boolean" }, "lineCount": { "type": "integer" }, "exportCount": { "type": "integer" }, "lastExportedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "rowVersion": { "type": "integer" } }, "additionalProperties": true }, "JournalDetail": { "allOf": [ { "$ref": "#/components/schemas/Journal" }, { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "object", "properties": { "lineNo": { "type": "integer" }, "account": { "type": "string" }, "costCentreCode": { "type": [ "string", "null" ] }, "departmentCode": { "type": [ "string", "null" ] }, "analysis": { "type": "object", "additionalProperties": { "type": "string" } }, "debit": { "type": [ "string", "null" ] }, "credit": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "glMappingKey": { "type": "string" }, "employeeCode": { "type": [ "string", "null" ] } } } }, "exports": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "versionNo": { "type": "integer" }, "format": { "type": "string", "enum": [ "CSV", "XLSX" ] }, "layoutCode": { "type": [ "string", "null" ] }, "layoutName": { "type": [ "string", "null" ] }, "sha256": { "type": "string" }, "exportedAt": { "type": "string", "format": "date-time" }, "exportedBy": { "type": [ "string", "null" ] }, "unmasked": { "type": "boolean" } } } }, "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "reference": { "type": "string" }, "versionNo": { "type": "integer" }, "status": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } } } } ] }, "PayRunStatus": { "type": "string", "enum": [ "DRAFT", "CALCULATING", "CALCULATED", "IN_REVIEW", "APPROVED", "LOCKED", "PUBLISHED", "BANK_FILE_GENERATED", "PAYMENT_PARTIAL", "PAID", "CLOSED", "CANCELLED", "REVERSED" ] }, "PayRun": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "reference": { "type": "string" }, "runType": { "type": "string" }, "status": { "$ref": "#/components/schemas/PayRunStatus" }, "population": { "type": "string" }, "payGroup": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" } } }, "period": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "label": { "type": "string" }, "start": { "type": "string", "format": "date" }, "end": { "type": "string", "format": "date" }, "payDate": { "type": "string", "format": "date" }, "status": { "type": "string" } } }, "paymentDate": { "type": [ "string", "null" ], "format": "date" }, "headcount": { "type": "integer" }, "totals": { "type": "object", "description": "Decimal strings; null and masked: true without amount access.", "properties": { "gross": { "type": [ "string", "null" ] }, "deductions": { "type": [ "string", "null" ] }, "net": { "type": [ "string", "null" ] }, "employerContrib": { "type": [ "string", "null" ] }, "masked": { "type": "boolean" } } }, "exceptionCounts": { "type": "object", "properties": { "ERROR": { "type": "integer" }, "WARNING": { "type": "integer" }, "INFO": { "type": "integer" }, "unacknowledged": { "type": "integer" } } }, "calculatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "approvedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lockedAt": { "type": [ "string", "null" ], "format": "date-time" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resultHash": { "type": [ "string", "null" ] }, "rowVersion": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "MyPayslip": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "periodCode": { "type": "string" }, "periodLabel": { "type": "string" }, "periodLabelAr": { "type": "string" }, "payDate": { "type": [ "string", "null" ], "format": "date" }, "net": { "type": "string" }, "currency": { "type": "string" }, "versionNo": { "type": "integer" }, "revised": { "type": "boolean" }, "publishedAt": { "type": "string", "format": "date-time" } } }, "PayslipDocument": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "html": { "type": "string", "description": "Printable HTML of the payslip." }, "sha256": { "type": "string" }, "versionNo": { "type": "integer" }, "revised": { "type": "boolean" }, "periodCode": { "type": "string" }, "periodLabel": { "type": "string" }, "employeeCode": { "type": "string" }, "nameEn": { "type": "string" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "supersededAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "ExtEmployee": { "type": "object", "description": "One employment record.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Employment record id (use it as employeeId elsewhere)." }, "employeeCode": { "type": "string" }, "personId": { "type": "string", "format": "uuid" }, "givenName": { "type": "string" }, "middleName": { "type": [ "string", "null" ] }, "familyName": { "type": [ "string", "null" ] }, "preferredName": { "type": [ "string", "null" ] }, "givenNameAr": { "type": [ "string", "null" ] }, "familyNameAr": { "type": [ "string", "null" ] }, "nationality": { "type": [ "string", "null" ], "description": "ISO country code." }, "email": { "type": [ "string", "null" ], "description": "Work sign-in email, when the person has a user account." }, "status": { "$ref": "#/components/schemas/EmploymentStatus" }, "legalEntityId": { "type": [ "string", "null" ], "format": "uuid" }, "joiningDate": { "type": "string", "format": "date" }, "originalJoiningDate": { "type": "string", "format": "date" }, "exitDate": { "type": [ "string", "null" ], "format": "date" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "ExtPunch": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "employeeId": { "type": [ "string", "null" ], "format": "uuid", "description": "Null when the badge did not match anyone." }, "employeeCode": { "type": [ "string", "null" ] }, "sourceIdentity": { "type": "string", "description": "Badge, enrolment or user number as the device sent it." }, "eventAt": { "type": "string", "format": "date-time" }, "receivedAt": { "type": "string", "format": "date-time" }, "direction": { "type": [ "string", "null" ], "enum": [ "IN", "OUT", null ] }, "channel": { "type": "string" }, "device": { "type": [ "string", "null" ], "description": "Device code." }, "outcome": { "type": [ "string", "null" ] } } }, "ExtLeaveBalance": { "type": "object", "properties": { "employeeId": { "type": "string", "format": "uuid" }, "employeeCode": { "type": "string" }, "leaveType": { "type": "string", "description": "Leave type code." }, "leaveTypeName": { "type": "string" }, "carried": { "type": "number" }, "entitled": { "type": "number" }, "adjusted": { "type": "number" }, "taken": { "type": "number" }, "pending": { "type": "number" }, "available": { "type": [ "number", "null" ], "description": "carried + entitled + adjusted − taken − pending; null when unlimited." }, "unlimited": { "type": "boolean" } } }, "ExtPayRun": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "reference": { "type": "string" }, "runType": { "type": "string" }, "status": { "type": "string", "enum": [ "APPROVED", "LOCKED", "PUBLISHED", "BANK_FILE_GENERATED", "PAYMENT_PARTIAL", "PAID", "CLOSED" ] }, "periodId": { "type": "string", "format": "uuid" }, "paymentDate": { "type": [ "string", "null" ], "format": "date" }, "approvedAt": { "type": [ "string", "null" ], "format": "date-time" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "headcount": { "type": "integer" } } }, "ExtPayLine": { "type": "object", "description": "Amounts and components appear only when the key's creator holds the SALARY sensitive grant.", "properties": { "employeeId": { "type": "string", "format": "uuid" }, "employeeCode": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "costCenter": { "type": [ "string", "null" ] }, "paymentMethod": { "type": [ "string", "null" ] }, "gross": { "type": "number" }, "deductions": { "type": "number" }, "net": { "type": "number" }, "employerContribution": { "type": "number" }, "components": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "type": { "type": "string" }, "amount": { "type": "number" }, "quantity": { "type": [ "number", "null" ] } } } } } } }, "responses": { "E401": { "description": "Missing, invalid or expired access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "key": "CFG-001", "type": "ERROR", "message": "The session has expired. Sign in again.", "statusCode": 401, "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-18T09:15:02.118Z", "path": "/api/v1/…" } } } } }, "E403": { "description": "The caller lacks the permission (CFG-008) or the record is outside their data scope (CFG-009).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "key": "CFG-008", "type": "ERROR", "message": "You do not have permission to perform this action.", "statusCode": 403, "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-18T09:15:02.118Z", "path": "/api/v1/…" } } } } }, "E404": { "description": "No such record in your tenant (CFG-038).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "key": "CFG-038", "type": "ERROR", "message": "The requested record does not exist in the active tenant.", "statusCode": 404, "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-18T09:15:02.118Z", "path": "/api/v1/…" } } } } }, "E409": { "description": "Conflict: duplicate, stale version or concurrent change. Nothing was saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "key": "CFG-013", "type": "ERROR", "message": "This record changed after you opened it. Review the latest version before saving.", "statusCode": 409, "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-18T09:15:02.118Z", "path": "/api/v1/…", "currentRowVersion": 4 } } } } }, "E422": { "description": "Validation failed; details lists each problem by field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "key": "CFG-001", "type": "ERROR", "message": "Enter the joining date, e.g. 2024-03-01.", "statusCode": 422, "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-18T09:15:02.118Z", "path": "/api/v1/…", "details": [ { "field": "joiningDate", "key": "CFG-001", "message": "Enter the joining date, e.g. 2024-03-01.", "severity": "ERROR" } ] } } } } }, "E429": { "description": "Rate limit exceeded. Wait and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "X401": { "description": "No key, or the key is invalid, expired or revoked, or its creator can no longer sign in.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "key": "CFG-001", "type": "ERROR", "message": "The API key is not valid, has expired or was revoked.", "statusCode": 401, "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-20T09:15:02.118Z", "path": "/api/v1/ext/…" } } } } }, "X403": { "description": "The key does not hold the scope the endpoint needs, or its creator lost that permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "key": "CFG-008", "type": "ERROR", "message": "You do not have permission to perform this action.", "statusCode": 403, "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-20T09:15:02.118Z", "path": "/api/v1/ext/…" } } } } }, "X404": { "description": "No such record, or it is outside the key creator's data scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "key": "CFG-001", "type": "ERROR", "message": "No employee with that id.", "statusCode": 404, "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-20T09:15:02.118Z", "path": "/api/v1/ext/…" } } } } }, "X422": { "description": "A query parameter or the body failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "key": "CFG-001", "type": "ERROR", "message": "Validation failed.", "statusCode": 422, "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-20T09:15:02.118Z", "path": "/api/v1/ext/…" } } } } }, "X429": { "description": "The key's per-minute limit was reached (default 120). Wait the Retry-After seconds. X-RateLimit-Limit and X-RateLimit-Remaining come with every response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "key": "CFG-001", "type": "ERROR", "message": "This API key is sending too many requests. Slow down and retry after the Retry-After seconds.", "statusCode": 429, "correlationId": "6f1c2b9e-4d1a-4b7e-9f0e-2a7c5d3e8b41", "timestamp": "2026-10-20T09:15:02.118Z", "path": "/api/v1/ext/…" } } } } } } } }