{
    "openapi": "3.1.0",
    "info": {
        "title": "AR ADMS Cloud API",
        "version": "1.0.0",
        "summary": "Attendance, employees and devices of organizations using AR ADMS Cloud.",
        "description": "REST API for ERP, HRM, payroll, school management and other software.\n\n* **Organization clients** belong to one organization and use the `client_credentials` grant.\n* **Developer apps** are registered in the developer portal; each organization connects them\n  with the `authorization_code` grant (PKCE S256) and can disconnect them at any time.\n\nEvery response from `/api/v1` uses the same envelope: `success`, optional `message`, `data`\nand optional `meta`. Errors carry `error.code` (stable, machine-readable), `error.message`\nand sometimes `error.details`. Times are ISO 8601 in the organization's time zone; dates are\n`YYYY-MM-DD` in that zone. IDs are lowercase ULIDs.\n",
        "contact": {
            "name": "AR Technologies Ltd."
        }
    },
    "servers": [
        {
            "url": "/",
            "description": "The server this document was downloaded from."
        }
    ],
    "tags": [
        {
            "name": "Authentication",
            "description": "Get access tokens."
        },
        {
            "name": "Organization",
            "description": "The organization the token belongs to and its branches."
        },
        {
            "name": "Employees",
            "description": "Employees and the user IDs they have on devices."
        },
        {
            "name": "Devices",
            "description": "Biometric devices and remote commands."
        },
        {
            "name": "Attendance",
            "description": "Calculated daily attendance, raw punches and leave."
        },
        {
            "name": "Reports",
            "description": "The same numbers as the reports in the web panel."
        },
        {
            "name": "Webhooks",
            "description": "Endpoints that receive events from this organization, owned by the calling client. An\nendpoint gets only the events the client's read scopes cover, and is deleted when the client\nis revoked or the organization disconnects the app. The event payloads are listed under\nWebhooks in this document.\n"
        }
    ],
    "security": [
        {
            "organizationClient": []
        },
        {
            "developerApp": []
        }
    ],
    "paths": {
        "/api/oauth/token": {
            "post": {
                "tags": [
                    "Authentication"
                ],
                "operationId": "issueToken",
                "summary": "Get an access token",
                "description": "Send client credentials in the form body (`client_id`, `client_secret`) or as HTTP Basic\nauthentication. Access tokens last 1 hour. Developer apps also get a refresh token that\nlasts 30 days and works once: every refresh returns a new pair, and reusing an old refresh\ntoken revokes the whole chain. Errors here use the OAuth 2.0 format\n(`error`, `error_description`), not the API envelope.\n",
                "security": [],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/x-www-form-urlencoded": {
                            "schema": {
                                "$ref": "#/components/schemas/TokenRequest"
                            }
                        },
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/TokenRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Token issued.",
                        "headers": {
                            "Cache-Control": {
                                "schema": {
                                    "type": "string",
                                    "example": "no-store"
                                }
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/TokenResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad grant, code, verifier or scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/OAuthError"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unknown client, wrong secret, revoked client or IP not allowed.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/OAuthError"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/organization": {
            "get": {
                "tags": [
                    "Organization"
                ],
                "operationId": "getOrganization",
                "summary": "The organization",
                "x-scope": "organization.read",
                "security": [
                    {
                        "organizationClient": [
                            "organization.read"
                        ]
                    },
                    {
                        "developerApp": [
                            "organization.read"
                        ]
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/OrganizationResponse"
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/api/v1/branches": {
            "get": {
                "tags": [
                    "Organization"
                ],
                "operationId": "listBranches",
                "summary": "Branches",
                "x-scope": "branches.read",
                "security": [
                    {
                        "organizationClient": [
                            "branches.read"
                        ]
                    },
                    {
                        "developerApp": [
                            "branches.read"
                        ]
                    }
                ],
                "responses": {
                    "200": {
                        "description": "All branches, by name.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/BranchListResponse"
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/api/v1/employees": {
            "get": {
                "tags": [
                    "Employees"
                ],
                "operationId": "listEmployees",
                "summary": "List employees",
                "x-scope": "employees.read",
                "security": [
                    {
                        "organizationClient": [
                            "employees.read"
                        ]
                    },
                    {
                        "developerApp": [
                            "employees.read"
                        ]
                    }
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/BranchId"
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "description": "Which employees to return.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "active",
                                "inactive",
                                "all"
                            ],
                            "default": "active"
                        }
                    },
                    {
                        "name": "updated_since",
                        "in": "query",
                        "description": "Only employees changed at or after this time (ISO 8601). Use it to sync changes.",
                        "schema": {
                            "type": "string",
                            "format": "date-time"
                        }
                    },
                    {
                        "name": "device_user_id",
                        "in": "query",
                        "description": "Only the employee who has this user ID on devices.",
                        "schema": {
                            "type": "string",
                            "maxLength": 32
                        }
                    },
                    {
                        "$ref": "#/components/parameters/Page"
                    },
                    {
                        "$ref": "#/components/parameters/PerPage"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "One page of employees, oldest first.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/EmployeePageResponse"
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            },
            "post": {
                "tags": [
                    "Employees"
                ],
                "operationId": "createEmployee",
                "summary": "Create an employee",
                "description": "Counts against the organization's employee limit. `device_user_ids` links the IDs the\nemployee uses on every device of the organization; punches already received with those\nIDs are attached and attendance is recalculated.\n",
                "x-scope": "employees.write",
                "security": [
                    {
                        "organizationClient": [
                            "employees.write"
                        ]
                    },
                    {
                        "developerApp": [
                            "employees.write"
                        ]
                    }
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/EmployeeCreate"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/EmployeeResponse"
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/api/v1/employees/{employee}": {
            "parameters": [
                {
                    "name": "employee",
                    "in": "path",
                    "required": true,
                    "description": "Employee ID.",
                    "schema": {
                        "type": "string",
                        "example": "01jcz8x4m2q7v9t3k5h6n8p0rs"
                    }
                }
            ],
            "get": {
                "tags": [
                    "Employees"
                ],
                "operationId": "getEmployee",
                "summary": "Get an employee",
                "x-scope": "employees.read",
                "security": [
                    {
                        "organizationClient": [
                            "employees.read"
                        ]
                    },
                    {
                        "developerApp": [
                            "employees.read"
                        ]
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/EmployeeResponse"
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            },
            "patch": {
                "tags": [
                    "Employees"
                ],
                "operationId": "updateEmployee",
                "summary": "Update an employee",
                "description": "Send only the fields to change. `device_user_ids`, when sent, replaces the full list.\nSetting `status` to `inactive` stops attendance tracking; reactivating counts against the\nemployee limit again.\n",
                "x-scope": "employees.write",
                "security": [
                    {
                        "organizationClient": [
                            "employees.write"
                        ]
                    },
                    {
                        "developerApp": [
                            "employees.write"
                        ]
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/EmployeeUpdate"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Updated.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/EmployeeResponse"
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/api/v1/devices": {
            "get": {
                "tags": [
                    "Devices"
                ],
                "operationId": "listDevices",
                "summary": "List devices",
                "x-scope": "devices.read",
                "security": [
                    {
                        "organizationClient": [
                            "devices.read"
                        ]
                    },
                    {
                        "developerApp": [
                            "devices.read"
                        ]
                    }
                ],
                "responses": {
                    "200": {
                        "description": "All devices, by name.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/DeviceListResponse"
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/api/v1/devices/{device}": {
            "get": {
                "tags": [
                    "Devices"
                ],
                "operationId": "getDevice",
                "summary": "Get a device",
                "x-scope": "devices.read",
                "security": [
                    {
                        "organizationClient": [
                            "devices.read"
                        ]
                    },
                    {
                        "developerApp": [
                            "devices.read"
                        ]
                    }
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/DeviceId"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/DeviceResponse"
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/api/v1/devices/{device}/sync": {
            "post": {
                "tags": [
                    "Devices"
                ],
                "operationId": "syncDevice",
                "summary": "Ask a device to send its punches",
                "description": "Queues a command for the device (ADMS) or its Windows Collector. The device picks it up\non its next contact, usually within a minute. Poll `GET /api/v1/device-commands/{id}`\nfor the result. If a sync is already waiting, that command is returned instead of a new one.\n",
                "x-scope": "devices.command",
                "security": [
                    {
                        "organizationClient": [
                            "devices.command"
                        ]
                    },
                    {
                        "developerApp": [
                            "devices.command"
                        ]
                    }
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/DeviceId"
                    },
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "responses": {
                    "202": {
                        "description": "Sync requested (or already pending).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/DeviceCommandResponse"
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/api/v1/device-commands/{command}": {
            "get": {
                "tags": [
                    "Devices"
                ],
                "operationId": "getDeviceCommand",
                "summary": "Get a command's status",
                "x-scope": "devices.read",
                "security": [
                    {
                        "organizationClient": [
                            "devices.read"
                        ]
                    },
                    {
                        "developerApp": [
                            "devices.read"
                        ]
                    }
                ],
                "parameters": [
                    {
                        "name": "command",
                        "in": "path",
                        "required": true,
                        "description": "Command ID returned by the sync request.",
                        "schema": {
                            "type": "string",
                            "example": "01jd0a1b2c3d4e5f6g7h8j9k0m"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/DeviceCommandResponse"
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/api/v1/attendance": {
            "get": {
                "tags": [
                    "Attendance"
                ],
                "operationId": "listAttendance",
                "summary": "Daily attendance",
                "description": "One row per employee per day, as calculated by the attendance engine (shifts, grace,\novertime, weekends, holidays, leave and corrections applied). Days are recalculated when\nlate punches arrive or HR corrects them; use `updated_since` to pick up changes.\nAt most 62 days per request.\n",
                "x-scope": "attendance.read",
                "security": [
                    {
                        "organizationClient": [
                            "attendance.read"
                        ]
                    },
                    {
                        "developerApp": [
                            "attendance.read"
                        ]
                    }
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/From"
                    },
                    {
                        "$ref": "#/components/parameters/To"
                    },
                    {
                        "$ref": "#/components/parameters/EmployeeId"
                    },
                    {
                        "$ref": "#/components/parameters/BranchId"
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "$ref": "#/components/schemas/AttendanceStatus"
                        }
                    },
                    {
                        "name": "updated_since",
                        "in": "query",
                        "description": "Only rows calculated at or after this time (ISO 8601).",
                        "schema": {
                            "type": "string",
                            "format": "date-time"
                        }
                    },
                    {
                        "$ref": "#/components/parameters/Page"
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "description": "Rows per page, 1–200.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 200,
                            "default": 100
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "One page, ordered by date then employee.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/AttendancePageResponse"
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/api/v1/punches": {
            "get": {
                "tags": [
                    "Attendance"
                ],
                "operationId": "listPunches",
                "summary": "Raw punches",
                "description": "Every punch exactly as devices sent it, oldest first, including punches from device user\nIDs not linked to any employee yet. At most 31 days per request. Uses cursor pagination:\nrepeat the request with `cursor` set to `meta.next_cursor` until it is `null`.\n",
                "x-scope": "attendance.raw.read",
                "security": [
                    {
                        "organizationClient": [
                            "attendance.raw.read"
                        ]
                    },
                    {
                        "developerApp": [
                            "attendance.raw.read"
                        ]
                    }
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/From"
                    },
                    {
                        "$ref": "#/components/parameters/To"
                    },
                    {
                        "$ref": "#/components/parameters/EmployeeId"
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "description": "`meta.next_cursor` from the previous page.",
                        "schema": {
                            "type": "string",
                            "maxLength": 100
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "description": "Punches per page, 1–200.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 200,
                            "default": 200
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "One page of punches.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PunchPageResponse"
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/api/v1/leave": {
            "get": {
                "tags": [
                    "Attendance"
                ],
                "operationId": "listLeave",
                "summary": "Leave applications",
                "description": "Applications that overlap the date range (at most 366 days).",
                "x-scope": "leave.read",
                "security": [
                    {
                        "organizationClient": [
                            "leave.read"
                        ]
                    },
                    {
                        "developerApp": [
                            "leave.read"
                        ]
                    }
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/From"
                    },
                    {
                        "$ref": "#/components/parameters/To"
                    },
                    {
                        "$ref": "#/components/parameters/EmployeeId"
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "pending",
                                "approved",
                                "rejected",
                                "cancelled"
                            ]
                        }
                    },
                    {
                        "$ref": "#/components/parameters/Page"
                    },
                    {
                        "$ref": "#/components/parameters/PerPage"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "One page, by start date.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/LeavePageResponse"
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/api/v1/reports/monthly-summary": {
            "get": {
                "tags": [
                    "Reports"
                ],
                "operationId": "monthlySummary",
                "summary": "Monthly summary per employee",
                "x-scope": "reports.read",
                "security": [
                    {
                        "organizationClient": [
                            "reports.read"
                        ]
                    },
                    {
                        "developerApp": [
                            "reports.read"
                        ]
                    }
                ],
                "parameters": [
                    {
                        "name": "month",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^\\d{4}-\\d{2}$",
                            "example": "2026-11"
                        }
                    },
                    {
                        "$ref": "#/components/parameters/BranchId"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "One row per employee.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MonthlySummaryResponse"
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/api/v1/webhooks": {
            "get": {
                "tags": [
                    "Webhooks"
                ],
                "operationId": "listWebhooks",
                "summary": "List your webhook endpoints",
                "description": "Endpoints this client created in this organization.",
                "x-scope": "webhooks.manage",
                "security": [
                    {
                        "organizationClient": [
                            "webhooks.manage"
                        ]
                    },
                    {
                        "developerApp": [
                            "webhooks.manage"
                        ]
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/WebhookEndpointListResponse"
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            },
            "post": {
                "tags": [
                    "Webhooks"
                ],
                "operationId": "createWebhook",
                "summary": "Create a webhook endpoint",
                "description": "The URL must use https and resolve to a public address. Every event in `events` must be\ncovered by one of the token's read scopes (`attendance.raw_received` needs\n`attendance.raw.read`, `attendance.*` needs `attendance.read`, `employee.*` needs\n`employees.read`, `device.*`, `collector.*` and `sync.*` need `devices.read`).\nThe response contains the signing `secret` once. At most 5 endpoints per client and\norganization; the organization's plan must include webhooks.\n",
                "x-scope": "webhooks.manage",
                "security": [
                    {
                        "organizationClient": [
                            "webhooks.manage"
                        ]
                    },
                    {
                        "developerApp": [
                            "webhooks.manage"
                        ]
                    }
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/WebhookEndpointCreate"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created. Store `data.secret` now.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/WebhookEndpointSecretResponse"
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/api/v1/webhooks/{webhook}": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/WebhookId"
                }
            ],
            "get": {
                "tags": [
                    "Webhooks"
                ],
                "operationId": "getWebhook",
                "summary": "Get a webhook endpoint",
                "x-scope": "webhooks.manage",
                "security": [
                    {
                        "organizationClient": [
                            "webhooks.manage"
                        ]
                    },
                    {
                        "developerApp": [
                            "webhooks.manage"
                        ]
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/WebhookEndpointResponse"
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            },
            "patch": {
                "tags": [
                    "Webhooks"
                ],
                "operationId": "updateWebhook",
                "summary": "Update a webhook endpoint",
                "description": "Send only what changes. `status: active` switches an endpoint on again after it was\nswitched off (by you, by the organization, or automatically after 30 failed attempts in a row).\n",
                "x-scope": "webhooks.manage",
                "security": [
                    {
                        "organizationClient": [
                            "webhooks.manage"
                        ]
                    },
                    {
                        "developerApp": [
                            "webhooks.manage"
                        ]
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/WebhookEndpointUpdate"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Updated.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/WebhookEndpointResponse"
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            },
            "delete": {
                "tags": [
                    "Webhooks"
                ],
                "operationId": "deleteWebhook",
                "summary": "Delete a webhook endpoint",
                "description": "Also deletes its delivery log.",
                "x-scope": "webhooks.manage",
                "security": [
                    {
                        "organizationClient": [
                            "webhooks.manage"
                        ]
                    },
                    {
                        "developerApp": [
                            "webhooks.manage"
                        ]
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Deleted.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/EmptyResponse"
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/api/v1/webhooks/{webhook}/rotate-secret": {
            "post": {
                "tags": [
                    "Webhooks"
                ],
                "operationId": "rotateWebhookSecret",
                "summary": "Create a new signing secret",
                "description": "Requests are signed with the new secret immediately; the old one stops working.",
                "x-scope": "webhooks.manage",
                "security": [
                    {
                        "organizationClient": [
                            "webhooks.manage"
                        ]
                    },
                    {
                        "developerApp": [
                            "webhooks.manage"
                        ]
                    }
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/WebhookId"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "New secret in `data.secret`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/WebhookEndpointSecretResponse"
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/api/v1/webhooks/{webhook}/test": {
            "post": {
                "tags": [
                    "Webhooks"
                ],
                "operationId": "testWebhook",
                "summary": "Send a test event",
                "description": "Sends a `webhook.test` event to this endpoint only.",
                "x-scope": "webhooks.manage",
                "security": [
                    {
                        "organizationClient": [
                            "webhooks.manage"
                        ]
                    },
                    {
                        "developerApp": [
                            "webhooks.manage"
                        ]
                    }
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/WebhookId"
                    }
                ],
                "responses": {
                    "202": {
                        "description": "Queued; the delivery is returned.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/WebhookDeliveryResponse"
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/api/v1/webhooks/{webhook}/deliveries": {
            "get": {
                "tags": [
                    "Webhooks"
                ],
                "operationId": "listWebhookDeliveries",
                "summary": "Delivery log",
                "description": "Newest first. Kept for 30 days.",
                "x-scope": "webhooks.manage",
                "security": [
                    {
                        "organizationClient": [
                            "webhooks.manage"
                        ]
                    },
                    {
                        "developerApp": [
                            "webhooks.manage"
                        ]
                    }
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/WebhookId"
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "pending",
                                "succeeded",
                                "failed"
                            ]
                        }
                    },
                    {
                        "$ref": "#/components/parameters/Page"
                    },
                    {
                        "$ref": "#/components/parameters/PerPage"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "One page of deliveries.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/WebhookDeliveryPageResponse"
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/api/v1/webhooks/{webhook}/deliveries/{delivery}/resend": {
            "post": {
                "tags": [
                    "Webhooks"
                ],
                "operationId": "resendWebhookDelivery",
                "summary": "Send a delivery again",
                "description": "Sends the same event (same `id`) again now, with a fresh retry schedule.",
                "x-scope": "webhooks.manage",
                "security": [
                    {
                        "organizationClient": [
                            "webhooks.manage"
                        ]
                    },
                    {
                        "developerApp": [
                            "webhooks.manage"
                        ]
                    }
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/WebhookId"
                    },
                    {
                        "name": "delivery",
                        "in": "path",
                        "required": true,
                        "description": "Delivery ID from the delivery log.",
                        "schema": {
                            "type": "string",
                            "example": "01jd3m2n4p6r8t0v2x4z6b8d0f"
                        }
                    }
                ],
                "responses": {
                    "202": {
                        "description": "Queued.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/WebhookDeliveryResponse"
                                }
                            }
                        }
                    },
                    "default": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        }
    },
    "webhooks": {
        "attendance.raw_received": {
            "post": {
                "summary": "New punches",
                "description": "Punches that were just stored, up to 100 per event, oldest first. The same punch is never sent twice.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/EventRawReceived"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Any 2xx status means delivered."
                    }
                }
            }
        },
        "attendance.processed": {
            "post": {
                "summary": "A day was calculated or changed",
                "description": "Sent when something visible in the day changed. Days can be recalculated later (late punches, corrections); keep the newest `calculated_at` per employee and date.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/EventAttendanceProcessed"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Any 2xx status means delivered."
                    }
                }
            }
        },
        "attendance.corrected": {
            "post": {
                "summary": "HR corrected a day",
                "description": "A correction was approved. The recalculated day follows as attendance.processed.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/EventAttendanceCorrected"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Any 2xx status means delivered."
                    }
                }
            }
        },
        "employee.created": {
            "post": {
                "summary": "An employee was added",
                "description": "The employee as GET /api/v1/employees/{id} returns it.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/EventEmployee"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Any 2xx status means delivered."
                    }
                }
            }
        },
        "employee.updated": {
            "post": {
                "summary": "An employee changed",
                "description": "Details, status or device user IDs changed.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/EventEmployee"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Any 2xx status means delivered."
                    }
                }
            }
        },
        "device.online": {
            "post": {
                "summary": "A device came online",
                "description": "The device made contact again.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/EventDevice"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Any 2xx status means delivered."
                    }
                }
            }
        },
        "device.offline": {
            "post": {
                "summary": "A device went offline",
                "description": "No contact for 2 minutes (ADMS) or the Collector cannot reach it.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/EventDevice"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Any 2xx status means delivered."
                    }
                }
            }
        },
        "collector.online": {
            "post": {
                "summary": "A Windows Collector came online",
                "description": "A heartbeat arrived after the Collector was offline.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/EventCollector"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Any 2xx status means delivered."
                    }
                }
            }
        },
        "collector.offline": {
            "post": {
                "summary": "A Windows Collector went offline",
                "description": "No heartbeat for 3 minutes.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/EventCollector"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Any 2xx status means delivered."
                    }
                }
            }
        },
        "sync.completed": {
            "post": {
                "summary": "A device sync finished",
                "description": "A sync requested in the panel or with POST /api/v1/devices/{id}/sync finished.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/EventSync"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Any 2xx status means delivered."
                    }
                }
            }
        },
        "sync.failed": {
            "post": {
                "summary": "A device sync failed",
                "description": "The device or Collector reported a failure.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/EventSync"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Any 2xx status means delivered."
                    }
                }
            }
        },
        "webhook.test": {
            "post": {
                "summary": "Test event",
                "description": "Sent by the Send test event button or POST /api/v1/webhooks/{id}/test.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/EventTest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Any 2xx status means delivered."
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "organizationClient": {
                "type": "oauth2",
                "description": "A client created by the organization under Settings → API access.",
                "flows": {
                    "clientCredentials": {
                        "tokenUrl": "/api/oauth/token",
                        "scopes": {
                            "organization.read": "Read the organization profile",
                            "branches.read": "Read branches",
                            "employees.read": "Read employees and their device user IDs",
                            "employees.write": "Create and update employees",
                            "devices.read": "Read devices and their status",
                            "devices.command": "Ask devices to sync punches",
                            "attendance.read": "Read daily attendance results",
                            "attendance.raw.read": "Read raw punches from devices",
                            "leave.read": "Read leave applications",
                            "reports.read": "Read attendance reports",
                            "webhooks.manage": "Create webhooks that send the events allowed by the read permissions"
                        }
                    }
                }
            },
            "developerApp": {
                "type": "oauth2",
                "description": "An app registered in the developer portal and connected by an organization.",
                "flows": {
                    "authorizationCode": {
                        "authorizationUrl": "/oauth/authorize",
                        "tokenUrl": "/api/oauth/token",
                        "refreshUrl": "/api/oauth/token",
                        "scopes": {
                            "organization.read": "Read the organization profile",
                            "branches.read": "Read branches",
                            "employees.read": "Read employees and their device user IDs",
                            "employees.write": "Create and update employees",
                            "devices.read": "Read devices and their status",
                            "devices.command": "Ask devices to sync punches",
                            "attendance.read": "Read daily attendance results",
                            "attendance.raw.read": "Read raw punches from devices",
                            "leave.read": "Read leave applications",
                            "reports.read": "Read attendance reports",
                            "webhooks.manage": "Create webhooks that send the events allowed by the read permissions"
                        }
                    }
                }
            }
        },
        "parameters": {
            "From": {
                "name": "from",
                "in": "query",
                "description": "First day (organization time zone). Default today.",
                "schema": {
                    "type": "string",
                    "format": "date",
                    "example": "2026-11-01"
                }
            },
            "To": {
                "name": "to",
                "in": "query",
                "description": "Last day, inclusive. Default `from`.",
                "schema": {
                    "type": "string",
                    "format": "date",
                    "example": "2026-11-30"
                }
            },
            "EmployeeId": {
                "name": "employee_id",
                "in": "query",
                "description": "Only this employee.",
                "schema": {
                    "type": "string"
                }
            },
            "BranchId": {
                "name": "branch_id",
                "in": "query",
                "description": "Only this branch.",
                "schema": {
                    "type": "string"
                }
            },
            "DeviceId": {
                "name": "device",
                "in": "path",
                "required": true,
                "description": "Device ID.",
                "schema": {
                    "type": "string",
                    "example": "01jcz7r5t1a2b3c4d5e6f7g8h9"
                }
            },
            "Page": {
                "name": "page",
                "in": "query",
                "schema": {
                    "type": "integer",
                    "minimum": 1,
                    "default": 1
                }
            },
            "PerPage": {
                "name": "per_page",
                "in": "query",
                "description": "Items per page, 1–200.",
                "schema": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 200,
                    "default": 50
                }
            },
            "WebhookId": {
                "name": "webhook",
                "in": "path",
                "required": true,
                "description": "Webhook endpoint ID.",
                "schema": {
                    "type": "string",
                    "example": "01jd3k4m6p8r0t2v4x6z8b0d2f"
                }
            },
            "IdempotencyKey": {
                "name": "Idempotency-Key",
                "in": "header",
                "description": "Any unique string (1–100 of `A-Z a-z 0-9 _ . : -`). Retrying with the same key within\n24 hours returns the first response (header `Idempotent-Replayed: true`) instead of doing\nthe work twice. Reusing a key for a different body is an error.\n",
                "schema": {
                    "type": "string",
                    "maxLength": 100,
                    "example": "payroll-sync-2026-11-17-E1"
                }
            }
        },
        "responses": {
            "Error": {
                "description": "Error. Common codes — 401: `invalid_token`, `token_expired`, `client_revoked`,\n`app_disconnected`; 403: `insufficient_scope`, `ip_not_allowed`, `organization_unavailable`,\n`api_not_in_plan`, `developer_suspended`, `organization_read_only`, `plan_limit_reached`;\n404: `not_found`; 409: `employee_code_taken`, `device_user_id_taken`, `device_disabled`;\n422: `validation_failed`, `range_too_large`, `invalid_cursor`, `invalid_idempotency_key`,\n`idempotency_key_reused`, `invalid_webhook_url`, `endpoint_limit_reached`; 403 (webhooks):\n`webhooks_not_in_plan`, `event_not_allowed`; 409: `endpoint_disabled`;\n429: `rate_limited`, `daily_quota_exceeded`.\n",
                "headers": {
                    "Retry-After": {
                        "description": "Seconds to wait (429 only).",
                        "schema": {
                            "type": "integer"
                        }
                    }
                },
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            }
        },
        "schemas": {
            "TokenRequest": {
                "type": "object",
                "required": [
                    "grant_type"
                ],
                "properties": {
                    "grant_type": {
                        "type": "string",
                        "enum": [
                            "client_credentials",
                            "authorization_code",
                            "refresh_token"
                        ]
                    },
                    "client_id": {
                        "type": "string",
                        "description": "Unless sent as HTTP Basic."
                    },
                    "client_secret": {
                        "type": "string",
                        "description": "Unless sent as HTTP Basic."
                    },
                    "scope": {
                        "type": "string",
                        "description": "Space-separated. Optional: defaults to every scope the client has (client_credentials) or that was granted (refresh_token)."
                    },
                    "code": {
                        "type": "string",
                        "description": "authorization_code only."
                    },
                    "redirect_uri": {
                        "type": "string",
                        "description": "authorization_code only; the same value as in the authorization request."
                    },
                    "code_verifier": {
                        "type": "string",
                        "description": "authorization_code only; the PKCE verifier (43–128 characters)."
                    },
                    "refresh_token": {
                        "type": "string",
                        "description": "refresh_token only."
                    }
                }
            },
            "TokenResponse": {
                "type": "object",
                "required": [
                    "access_token",
                    "token_type",
                    "expires_in",
                    "scope"
                ],
                "properties": {
                    "access_token": {
                        "type": "string",
                        "example": "arat_8fK2…"
                    },
                    "token_type": {
                        "type": "string",
                        "enum": [
                            "Bearer"
                        ]
                    },
                    "expires_in": {
                        "type": "integer",
                        "example": 3600
                    },
                    "scope": {
                        "type": "string",
                        "example": "employees.read attendance.read"
                    },
                    "refresh_token": {
                        "type": "string",
                        "description": "Developer apps only. Works once.",
                        "example": "arrt_Q7m…"
                    },
                    "organization": {
                        "description": "Developer apps only. The organization that granted access.",
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string",
                                "example": "01jcz5k2n4p6r8t0v2x4z6b8d0"
                            },
                            "name": {
                                "type": "string",
                                "example": "Acme Garments Ltd."
                            }
                        }
                    }
                }
            },
            "OAuthError": {
                "type": "object",
                "required": [
                    "error",
                    "error_description"
                ],
                "properties": {
                    "error": {
                        "type": "string",
                        "enum": [
                            "invalid_request",
                            "invalid_client",
                            "invalid_grant",
                            "unauthorized_client",
                            "unsupported_grant_type",
                            "invalid_scope"
                        ]
                    },
                    "error_description": {
                        "type": "string"
                    }
                }
            },
            "Error": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "success",
                    "error"
                ],
                "properties": {
                    "success": {
                        "type": "boolean",
                        "enum": [
                            false
                        ]
                    },
                    "error": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                            "code",
                            "message"
                        ],
                        "properties": {
                            "code": {
                                "type": "string",
                                "example": "insufficient_scope"
                            },
                            "message": {
                                "type": "string",
                                "example": "This token lacks the \"attendance.read\" scope."
                            },
                            "details": {
                                "type": "object",
                                "description": "Field errors for `validation_failed` (field → list of messages), otherwise extra facts such as `required_scope`.",
                                "example": {
                                    "required_scope": "attendance.read"
                                }
                            }
                        }
                    }
                }
            },
            "PageMeta": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "pagination"
                ],
                "properties": {
                    "pagination": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                            "page",
                            "per_page",
                            "total",
                            "last_page"
                        ],
                        "properties": {
                            "page": {
                                "type": "integer",
                                "example": 1
                            },
                            "per_page": {
                                "type": "integer",
                                "example": 50
                            },
                            "total": {
                                "type": "integer",
                                "example": 128
                            },
                            "last_page": {
                                "type": "integer",
                                "example": 3
                            }
                        }
                    }
                }
            },
            "Ref": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "id",
                    "name"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "01jcz6f0a9b8c7d6e5f4g3h2j1"
                    },
                    "name": {
                        "type": "string",
                        "example": "Head Office"
                    }
                }
            },
            "EmployeeRef": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "id",
                    "code",
                    "name"
                ],
                "properties": {
                    "id": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "01jcz8x4m2q7v9t3k5h6n8p0rs"
                    },
                    "code": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "E1001"
                    },
                    "name": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "Rahim Uddin"
                    }
                }
            },
            "Organization": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "id",
                    "name",
                    "timezone",
                    "country",
                    "currency",
                    "status"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "description": "The same ID as `organization.id` in developer-app token responses.",
                        "example": "01jcz5k2n4p6r8t0v2x4z6b8d0"
                    },
                    "name": {
                        "type": "string",
                        "example": "Acme Garments Ltd."
                    },
                    "timezone": {
                        "type": "string",
                        "example": "Asia/Dhaka"
                    },
                    "country": {
                        "type": "string",
                        "example": "BD"
                    },
                    "currency": {
                        "type": "string",
                        "example": "BDT"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "trial",
                            "active",
                            "suspended",
                            "cancelled"
                        ],
                        "example": "active"
                    }
                }
            },
            "Branch": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "id",
                    "code",
                    "name",
                    "timezone",
                    "weekend_days",
                    "status"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "01jcz6f0a9b8c7d6e5f4g3h2j1"
                    },
                    "code": {
                        "type": "string",
                        "example": "HO"
                    },
                    "name": {
                        "type": "string",
                        "example": "Head Office"
                    },
                    "timezone": {
                        "type": "string",
                        "example": "Asia/Dhaka"
                    },
                    "weekend_days": {
                        "type": "array",
                        "description": "ISO weekday numbers, 1 = Monday … 7 = Sunday.",
                        "items": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 7
                        },
                        "example": [
                            5
                        ]
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "active",
                            "inactive"
                        ],
                        "example": "active"
                    }
                }
            },
            "Employee": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "id",
                    "code",
                    "name",
                    "phone",
                    "email",
                    "branch",
                    "department",
                    "designation",
                    "joining_date",
                    "status",
                    "device_user_ids",
                    "created_at",
                    "updated_at"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "01jcz8x4m2q7v9t3k5h6n8p0rs"
                    },
                    "code": {
                        "type": "string",
                        "description": "The organization's own employee code (unique",
                        "case-insensitive).": null,
                        "example": "E1001"
                    },
                    "name": {
                        "type": "string",
                        "example": "Rahim Uddin"
                    },
                    "phone": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "+8801711000000"
                    },
                    "email": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "email",
                        "example": "rahim@example.com"
                    },
                    "branch": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/Ref"
                            },
                            {
                                "type": "null"
                            }
                        ]
                    },
                    "department": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "Production"
                    },
                    "designation": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "Operator"
                    },
                    "joining_date": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date",
                        "example": "2026-01-15"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "active",
                            "inactive"
                        ],
                        "example": "active"
                    },
                    "device_user_ids": {
                        "type": "array",
                        "description": "User IDs (PINs) this employee has on the organization's devices.",
                        "items": {
                            "type": "string"
                        },
                        "example": [
                            "1001"
                        ]
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "example": "2026-11-01T10:15:00+06:00"
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time",
                        "example": "2026-11-10T09:02:11+06:00"
                    }
                }
            },
            "EmployeeCreate": {
                "type": "object",
                "required": [
                    "name",
                    "code",
                    "branch_id"
                ],
                "properties": {
                    "name": {
                        "type": "string",
                        "maxLength": 150,
                        "example": "Rahim Uddin"
                    },
                    "code": {
                        "type": "string",
                        "maxLength": 40,
                        "pattern": "^[A-Za-z0-9._/-]+$",
                        "example": "E1001"
                    },
                    "branch_id": {
                        "type": "string",
                        "example": "01jcz6f0a9b8c7d6e5f4g3h2j1"
                    },
                    "department": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "maxLength": 120,
                        "description": "Created if it does not exist.",
                        "example": "Production"
                    },
                    "designation": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "maxLength": 120,
                        "description": "Created if it does not exist.",
                        "example": "Operator"
                    },
                    "phone": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "maxLength": 32,
                        "example": "+8801711000000"
                    },
                    "email": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "email",
                        "maxLength": 255,
                        "example": "rahim@example.com"
                    },
                    "joining_date": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date",
                        "description": "Attendance is tracked from this day.",
                        "example": "2026-01-15"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "active",
                            "inactive"
                        ],
                        "default": "active"
                    },
                    "device_user_ids": {
                        "type": "array",
                        "maxItems": 20,
                        "items": {
                            "type": "string",
                            "maxLength": 32,
                            "pattern": "^[A-Za-z0-9_-]+$"
                        },
                        "example": [
                            "1001"
                        ]
                    }
                }
            },
            "EmployeeUpdate": {
                "type": "object",
                "minProperties": 1,
                "example": {
                    "status": "inactive"
                },
                "properties": {
                    "name": {
                        "type": "string",
                        "maxLength": 150
                    },
                    "code": {
                        "type": "string",
                        "maxLength": 40,
                        "pattern": "^[A-Za-z0-9._/-]+$"
                    },
                    "branch_id": {
                        "type": "string"
                    },
                    "department": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "maxLength": 120
                    },
                    "designation": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "maxLength": 120
                    },
                    "phone": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "maxLength": 32
                    },
                    "email": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "email",
                        "maxLength": 255
                    },
                    "joining_date": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "active",
                            "inactive"
                        ]
                    },
                    "device_user_ids": {
                        "type": "array",
                        "maxItems": 20,
                        "description": "Replaces the whole list. Send [] to unlink every ID.",
                        "items": {
                            "type": "string",
                            "maxLength": 32,
                            "pattern": "^[A-Za-z0-9_-]+$"
                        }
                    }
                }
            },
            "Device": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "id",
                    "name",
                    "serial_number",
                    "connection",
                    "branch",
                    "status",
                    "model",
                    "firmware",
                    "last_seen_at",
                    "last_punch_at"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "01jcz7r5t1a2b3c4d5e6f7g8h9"
                    },
                    "name": {
                        "type": "string",
                        "example": "Main gate"
                    },
                    "serial_number": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "CQUJ214560123"
                    },
                    "connection": {
                        "type": "string",
                        "enum": [
                            "adms",
                            "collector"
                        ],
                        "description": "`adms`: the device talks to the cloud directly. `collector`: through a Windows Collector on the LAN.",
                        "example": "adms"
                    },
                    "branch": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/Ref"
                            },
                            {
                                "type": "null"
                            }
                        ]
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "unknown",
                            "online",
                            "offline",
                            "disabled"
                        ],
                        "example": "online"
                    },
                    "model": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "K50-A"
                    },
                    "firmware": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "Ver 6.60 Apr 28 2017"
                    },
                    "last_seen_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time",
                        "example": "2026-11-17T08:20:05+06:00"
                    },
                    "last_punch_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time",
                        "example": "2026-11-17T08:01:44+06:00"
                    }
                }
            },
            "DeviceCommand": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "id",
                    "device_id",
                    "type",
                    "status",
                    "requested_at",
                    "completed_at",
                    "expires_at"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "01jd0a1b2c3d4e5f6g7h8j9k0m"
                    },
                    "device_id": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "01jcz7r5t1a2b3c4d5e6f7g8h9"
                    },
                    "type": {
                        "type": "string",
                        "enum": [
                            "sync_attlog",
                            "get_info",
                            "set_time"
                        ],
                        "example": "sync_attlog"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "queued",
                            "delivered",
                            "succeeded",
                            "failed",
                            "expired",
                            "cancelled"
                        ],
                        "description": "`queued` → `delivered` (the device fetched it) → `succeeded` or `failed`. Commands not picked up in time become `expired`.",
                        "example": "queued"
                    },
                    "requested_at": {
                        "type": "string",
                        "format": "date-time",
                        "example": "2026-11-17T08:21:00+06:00"
                    },
                    "completed_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time",
                        "example": null
                    },
                    "expires_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time",
                        "example": "2026-11-17T09:21:00+06:00"
                    }
                }
            },
            "AttendanceStatus": {
                "type": "string",
                "enum": [
                    "present",
                    "half_day",
                    "absent",
                    "incomplete",
                    "in_progress",
                    "weekend",
                    "holiday",
                    "leave"
                ],
                "description": "`in_progress`: checked in and the shift is still running. `incomplete`: only one punch and\nthe day is over. `half_day` / `absent`: worked less than the shift's thresholds.\n"
            },
            "Attendance": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "employee",
                    "date",
                    "status",
                    "day_type",
                    "shift",
                    "check_in",
                    "check_out",
                    "worked_minutes",
                    "break_minutes",
                    "late_minutes",
                    "early_out_minutes",
                    "overtime_minutes",
                    "is_late",
                    "flags",
                    "needs_review",
                    "corrected",
                    "calculated_at"
                ],
                "properties": {
                    "employee": {
                        "$ref": "#/components/schemas/EmployeeRef"
                    },
                    "date": {
                        "type": "string",
                        "format": "date",
                        "example": "2026-11-16"
                    },
                    "status": {
                        "$ref": "#/components/schemas/AttendanceStatus"
                    },
                    "day_type": {
                        "type": "string",
                        "enum": [
                            "working",
                            "weekend",
                            "holiday"
                        ],
                        "example": "working"
                    },
                    "shift": {
                        "description": "The shift as it was when the day was calculated.",
                        "oneOf": [
                            {
                                "type": "object",
                                "additionalProperties": false,
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "example": "General"
                                    },
                                    "type": {
                                        "type": "string",
                                        "enum": [
                                            "fixed",
                                            "flexible"
                                        ],
                                        "example": "fixed"
                                    },
                                    "start": {
                                        "type": "string",
                                        "example": "09:00"
                                    },
                                    "end": {
                                        "type": "string",
                                        "example": "18:00"
                                    }
                                }
                            },
                            {
                                "type": "null"
                            }
                        ]
                    },
                    "check_in": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time",
                        "example": "2026-11-16T09:07:12+06:00"
                    },
                    "check_out": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time",
                        "example": "2026-11-16T18:04:40+06:00"
                    },
                    "worked_minutes": {
                        "type": "integer",
                        "example": 477
                    },
                    "break_minutes": {
                        "type": "integer",
                        "example": 60
                    },
                    "late_minutes": {
                        "type": "integer",
                        "example": 0
                    },
                    "early_out_minutes": {
                        "type": "integer",
                        "example": 0
                    },
                    "overtime_minutes": {
                        "type": "integer",
                        "example": 0
                    },
                    "is_late": {
                        "type": "boolean",
                        "example": false
                    },
                    "flags": {
                        "type": "array",
                        "description": "Notes from the engine, for example `late`, `early_out`, `missing_in`, `missing_out`, `odd_punches`, `clock_drift`, `insufficient_hours`, `worked_on_off_day`.",
                        "items": {
                            "type": "string"
                        },
                        "example": []
                    },
                    "needs_review": {
                        "type": "boolean",
                        "example": false
                    },
                    "corrected": {
                        "type": "boolean",
                        "description": "HR changed this day by hand.",
                        "example": false
                    },
                    "calculated_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time",
                        "example": "2026-11-16T18:05:02+06:00"
                    }
                }
            },
            "Punch": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "punched_at",
                    "device_local_time",
                    "device_user_id",
                    "employee",
                    "device_id",
                    "state",
                    "verify_mode",
                    "source"
                ],
                "properties": {
                    "punched_at": {
                        "type": "string",
                        "format": "date-time",
                        "example": "2026-11-16T09:07:12+06:00"
                    },
                    "device_local_time": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "The time exactly as the device's clock reported it.",
                        "example": "2026-11-16 09:07:12"
                    },
                    "device_user_id": {
                        "type": "string",
                        "example": "1001"
                    },
                    "employee": {
                        "oneOf": [
                            {
                                "type": "object",
                                "additionalProperties": false,
                                "required": [
                                    "id",
                                    "code"
                                ],
                                "properties": {
                                    "id": {
                                        "type": "string",
                                        "example": "01jcz8x4m2q7v9t3k5h6n8p0rs"
                                    },
                                    "code": {
                                        "type": "string",
                                        "example": "E1001"
                                    }
                                }
                            },
                            {
                                "type": "null"
                            }
                        ],
                        "description": "`null` while the device user ID is not linked to an employee."
                    },
                    "device_id": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "01jcz7r5t1a2b3c4d5e6f7g8h9"
                    },
                    "state": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "description": "Punch state key pressed on the device (0 check-in, 1 check-out, 2 break-out, 3 break-in, 4 OT-in, 5 OT-out).",
                        "example": 0
                    },
                    "verify_mode": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "description": "How the person was verified (device code: 1 fingerprint, 15 face, 4 card, 0 password…).",
                        "example": 1
                    },
                    "source": {
                        "type": "string",
                        "enum": [
                            "adms",
                            "collector",
                            "api",
                            "import"
                        ],
                        "example": "adms"
                    }
                }
            },
            "Leave": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "employee",
                    "type",
                    "from",
                    "to",
                    "half_day",
                    "days",
                    "status",
                    "reason",
                    "decided_at"
                ],
                "properties": {
                    "employee": {
                        "$ref": "#/components/schemas/EmployeeRef"
                    },
                    "type": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                            "code",
                            "name",
                            "paid"
                        ],
                        "properties": {
                            "code": {
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "example": "CL"
                            },
                            "name": {
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "example": "Casual leave"
                            },
                            "paid": {
                                "type": [
                                    "boolean",
                                    "null"
                                ],
                                "example": true
                            }
                        }
                    },
                    "from": {
                        "type": "string",
                        "format": "date",
                        "example": "2026-11-14"
                    },
                    "to": {
                        "type": "string",
                        "format": "date",
                        "example": "2026-11-15"
                    },
                    "half_day": {
                        "type": "boolean",
                        "example": false
                    },
                    "days": {
                        "type": "number",
                        "example": 2
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "pending",
                            "approved",
                            "rejected",
                            "cancelled"
                        ],
                        "example": "approved"
                    },
                    "reason": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "Family event"
                    },
                    "decided_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time",
                        "example": "2026-11-13T16:40:00+06:00"
                    }
                }
            },
            "MonthlySummaryRow": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "code",
                    "name",
                    "department",
                    "present_days",
                    "half_days",
                    "absent_days",
                    "incomplete_days",
                    "leave_days",
                    "holidays",
                    "weekend_days",
                    "late_days",
                    "late_minutes",
                    "early_out_days",
                    "worked_hours",
                    "overtime_hours"
                ],
                "properties": {
                    "code": {
                        "type": "string",
                        "example": "E1001"
                    },
                    "name": {
                        "type": "string",
                        "example": "Rahim Uddin"
                    },
                    "department": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "Production"
                    },
                    "present_days": {
                        "type": "number",
                        "example": 21
                    },
                    "half_days": {
                        "type": "number",
                        "example": 1
                    },
                    "absent_days": {
                        "type": "number",
                        "example": 0
                    },
                    "incomplete_days": {
                        "type": "number",
                        "example": 1
                    },
                    "leave_days": {
                        "type": "number",
                        "example": 2
                    },
                    "holidays": {
                        "type": "number",
                        "example": 1
                    },
                    "weekend_days": {
                        "type": "number",
                        "example": 4
                    },
                    "late_days": {
                        "type": "number",
                        "example": 3
                    },
                    "late_minutes": {
                        "type": "number",
                        "example": 41
                    },
                    "early_out_days": {
                        "type": "number",
                        "example": 0
                    },
                    "worked_hours": {
                        "type": "number",
                        "example": 182.5
                    },
                    "overtime_hours": {
                        "type": "number",
                        "example": 6
                    }
                }
            },
            "OrganizationResponse": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "success",
                    "data"
                ],
                "properties": {
                    "success": {
                        "type": "boolean",
                        "enum": [
                            true
                        ]
                    },
                    "data": {
                        "$ref": "#/components/schemas/Organization"
                    }
                }
            },
            "BranchListResponse": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "success",
                    "data"
                ],
                "properties": {
                    "success": {
                        "type": "boolean",
                        "enum": [
                            true
                        ]
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Branch"
                        }
                    }
                }
            },
            "EmployeeResponse": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "success",
                    "data"
                ],
                "properties": {
                    "success": {
                        "type": "boolean",
                        "enum": [
                            true
                        ]
                    },
                    "message": {
                        "type": "string",
                        "example": "Employee created."
                    },
                    "data": {
                        "$ref": "#/components/schemas/Employee"
                    }
                }
            },
            "EmployeePageResponse": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "success",
                    "data",
                    "meta"
                ],
                "properties": {
                    "success": {
                        "type": "boolean",
                        "enum": [
                            true
                        ]
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Employee"
                        }
                    },
                    "meta": {
                        "$ref": "#/components/schemas/PageMeta"
                    }
                }
            },
            "DeviceListResponse": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "success",
                    "data"
                ],
                "properties": {
                    "success": {
                        "type": "boolean",
                        "enum": [
                            true
                        ]
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Device"
                        }
                    }
                }
            },
            "DeviceResponse": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "success",
                    "data"
                ],
                "properties": {
                    "success": {
                        "type": "boolean",
                        "enum": [
                            true
                        ]
                    },
                    "data": {
                        "$ref": "#/components/schemas/Device"
                    }
                }
            },
            "DeviceCommandResponse": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "success",
                    "data"
                ],
                "properties": {
                    "success": {
                        "type": "boolean",
                        "enum": [
                            true
                        ]
                    },
                    "message": {
                        "type": "string",
                        "example": "Sync requested."
                    },
                    "data": {
                        "$ref": "#/components/schemas/DeviceCommand"
                    }
                }
            },
            "AttendancePageResponse": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "success",
                    "data",
                    "meta"
                ],
                "properties": {
                    "success": {
                        "type": "boolean",
                        "enum": [
                            true
                        ]
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Attendance"
                        }
                    },
                    "meta": {
                        "$ref": "#/components/schemas/PageMeta"
                    }
                }
            },
            "PunchPageResponse": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "success",
                    "data",
                    "meta"
                ],
                "properties": {
                    "success": {
                        "type": "boolean",
                        "enum": [
                            true
                        ]
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Punch"
                        }
                    },
                    "meta": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                            "next_cursor"
                        ],
                        "properties": {
                            "next_cursor": {
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "description": "Pass as `cursor` for the next page; `null` on the last page.",
                                "example": null
                            }
                        }
                    }
                }
            },
            "LeavePageResponse": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "success",
                    "data",
                    "meta"
                ],
                "properties": {
                    "success": {
                        "type": "boolean",
                        "enum": [
                            true
                        ]
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Leave"
                        }
                    },
                    "meta": {
                        "$ref": "#/components/schemas/PageMeta"
                    }
                }
            },
            "MonthlySummaryResponse": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "success",
                    "data",
                    "meta"
                ],
                "properties": {
                    "success": {
                        "type": "boolean",
                        "enum": [
                            true
                        ]
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/MonthlySummaryRow"
                        }
                    },
                    "meta": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                            "month"
                        ],
                        "properties": {
                            "month": {
                                "type": "string",
                                "example": "2026-11"
                            }
                        }
                    }
                }
            },
            "WebhookEndpoint": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "id",
                    "url",
                    "description",
                    "events",
                    "status",
                    "disabled_reason",
                    "consecutive_failures",
                    "last_success_at",
                    "last_failure_at",
                    "created_at"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "01jd3k4m6p8r0t2v4x6z8b0d2f"
                    },
                    "url": {
                        "type": "string",
                        "example": "https://payroll.example.com/hooks/ar"
                    },
                    "description": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "Payroll sync"
                    },
                    "events": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "example": [
                            "attendance.processed",
                            "employee.updated"
                        ]
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "active",
                            "disabled"
                        ],
                        "example": "active"
                    },
                    "disabled_reason": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": null
                    },
                    "consecutive_failures": {
                        "type": "integer",
                        "example": 0
                    },
                    "last_success_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time",
                        "example": "2026-11-18T09:12:44+06:00"
                    },
                    "last_failure_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time",
                        "example": null
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "example": "2026-11-18T09:00:00+06:00"
                    }
                }
            },
            "WebhookEndpointWithSecret": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "id",
                    "url",
                    "description",
                    "events",
                    "status",
                    "disabled_reason",
                    "consecutive_failures",
                    "last_success_at",
                    "last_failure_at",
                    "created_at",
                    "secret"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "01jd3k4m6p8r0t2v4x6z8b0d2f"
                    },
                    "url": {
                        "type": "string",
                        "example": "https://payroll.example.com/hooks/ar"
                    },
                    "description": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "Payroll sync"
                    },
                    "events": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "example": [
                            "attendance.processed",
                            "employee.updated"
                        ]
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "active",
                            "disabled"
                        ],
                        "example": "active"
                    },
                    "disabled_reason": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": null
                    },
                    "consecutive_failures": {
                        "type": "integer",
                        "example": 0
                    },
                    "last_success_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time",
                        "example": "2026-11-18T09:12:44+06:00"
                    },
                    "last_failure_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time",
                        "example": null
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "example": "2026-11-18T09:00:00+06:00"
                    },
                    "secret": {
                        "type": "string",
                        "description": "Signing secret. Shown only in this response.",
                        "example": "whsec_3q9Lx…"
                    }
                }
            },
            "WebhookEndpointCreate": {
                "type": "object",
                "required": [
                    "url",
                    "events"
                ],
                "properties": {
                    "url": {
                        "type": "string",
                        "maxLength": 500,
                        "example": "https://payroll.example.com/hooks/ar"
                    },
                    "events": {
                        "type": "array",
                        "minItems": 1,
                        "items": {
                            "type": "string",
                            "enum": [
                                "attendance.raw_received",
                                "attendance.processed",
                                "attendance.corrected",
                                "employee.created",
                                "employee.updated",
                                "device.online",
                                "device.offline",
                                "collector.online",
                                "collector.offline",
                                "sync.completed",
                                "sync.failed"
                            ]
                        },
                        "example": [
                            "attendance.processed",
                            "employee.updated"
                        ]
                    },
                    "description": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "maxLength": 200,
                        "example": "Payroll sync"
                    }
                }
            },
            "WebhookEndpointUpdate": {
                "type": "object",
                "minProperties": 1,
                "example": {
                    "status": "active"
                },
                "properties": {
                    "url": {
                        "type": "string",
                        "maxLength": 500
                    },
                    "events": {
                        "type": "array",
                        "minItems": 1,
                        "items": {
                            "type": "string"
                        }
                    },
                    "description": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "maxLength": 200
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "active",
                            "disabled"
                        ]
                    }
                }
            },
            "WebhookDelivery": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "id",
                    "event",
                    "status",
                    "attempts",
                    "http_status",
                    "error",
                    "duration_ms",
                    "created_at",
                    "delivered_at",
                    "next_attempt_at"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "01jd3m2n4p6r8t0v2x4z6b8d0f"
                    },
                    "event": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                            "id",
                            "type"
                        ],
                        "properties": {
                            "id": {
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "description": "The event ID your receiver sees in X-AR-Event-Id.",
                                "example": "01jd3m2a9b8c7d6e5f4g3h2j1k"
                            },
                            "type": {
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "example": "attendance.processed"
                            }
                        }
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "pending",
                            "succeeded",
                            "failed"
                        ],
                        "description": "`pending` with attempts > 0 means a retry is scheduled (`next_attempt_at`).",
                        "example": "succeeded"
                    },
                    "attempts": {
                        "type": "integer",
                        "example": 1
                    },
                    "http_status": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "description": "Status your server answered with last time.",
                        "example": 200
                    },
                    "error": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": null
                    },
                    "duration_ms": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "example": 184
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "example": "2026-11-18T09:12:44+06:00"
                    },
                    "delivered_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time",
                        "example": "2026-11-18T09:12:44+06:00"
                    },
                    "next_attempt_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time",
                        "example": null
                    }
                }
            },
            "WebhookEndpointListResponse": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "success",
                    "data"
                ],
                "properties": {
                    "success": {
                        "type": "boolean",
                        "enum": [
                            true
                        ]
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/WebhookEndpoint"
                        }
                    }
                }
            },
            "WebhookEndpointResponse": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "success",
                    "data"
                ],
                "properties": {
                    "success": {
                        "type": "boolean",
                        "enum": [
                            true
                        ]
                    },
                    "message": {
                        "type": "string",
                        "example": "Endpoint updated."
                    },
                    "data": {
                        "$ref": "#/components/schemas/WebhookEndpoint"
                    }
                }
            },
            "WebhookEndpointSecretResponse": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "success",
                    "data"
                ],
                "properties": {
                    "success": {
                        "type": "boolean",
                        "enum": [
                            true
                        ]
                    },
                    "message": {
                        "type": "string",
                        "example": "Endpoint created. Store the secret now: it is not shown again."
                    },
                    "data": {
                        "$ref": "#/components/schemas/WebhookEndpointWithSecret"
                    }
                }
            },
            "WebhookDeliveryResponse": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "success",
                    "data"
                ],
                "properties": {
                    "success": {
                        "type": "boolean",
                        "enum": [
                            true
                        ]
                    },
                    "message": {
                        "type": "string",
                        "example": "Test event queued."
                    },
                    "data": {
                        "$ref": "#/components/schemas/WebhookDelivery"
                    }
                }
            },
            "WebhookDeliveryPageResponse": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "success",
                    "data",
                    "meta"
                ],
                "properties": {
                    "success": {
                        "type": "boolean",
                        "enum": [
                            true
                        ]
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/WebhookDelivery"
                        }
                    },
                    "meta": {
                        "$ref": "#/components/schemas/PageMeta"
                    }
                }
            },
            "EmptyResponse": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "success",
                    "data"
                ],
                "properties": {
                    "success": {
                        "type": "boolean",
                        "enum": [
                            true
                        ]
                    },
                    "message": {
                        "type": "string",
                        "example": "Endpoint deleted."
                    },
                    "data": {
                        "type": "null"
                    }
                }
            },
            "EventRawReceived": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "id",
                    "type",
                    "created_at",
                    "organization",
                    "data"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "description": "Event ID; the same as X-AR-Event-Id. Use it to ignore duplicates.",
                        "example": "01jd3m2a9b8c7d6e5f4g3h2j1k"
                    },
                    "type": {
                        "type": "string",
                        "example": "attendance.raw_received"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "description": "When it happened (UTC).",
                        "example": "2026-11-18T03:12:40Z"
                    },
                    "organization": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                            "id"
                        ],
                        "properties": {
                            "id": {
                                "type": "string",
                                "description": "The organization's ID (GET /api/v1/organization).",
                                "example": "01jcz5k2n4p6r8t0v2x4z6b8d0"
                            }
                        }
                    },
                    "data": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                            "device",
                            "punches"
                        ],
                        "properties": {
                            "device": {
                                "type": "object",
                                "additionalProperties": false,
                                "required": [
                                    "id",
                                    "name",
                                    "serial_number"
                                ],
                                "properties": {
                                    "id": {
                                        "type": "string",
                                        "example": "01jcz7r5t1a2b3c4d5e6f7g8h9"
                                    },
                                    "name": {
                                        "type": "string",
                                        "example": "Main gate"
                                    },
                                    "serial_number": {
                                        "type": [
                                            "string",
                                            "null"
                                        ],
                                        "example": "CQUJ214560123"
                                    }
                                }
                            },
                            "punches": {
                                "type": "array",
                                "maxItems": 100,
                                "items": {
                                    "$ref": "#/components/schemas/Punch"
                                }
                            }
                        }
                    }
                }
            },
            "EventAttendanceProcessed": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "id",
                    "type",
                    "created_at",
                    "organization",
                    "data"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "description": "Event ID; the same as X-AR-Event-Id. Use it to ignore duplicates.",
                        "example": "01jd3m2a9b8c7d6e5f4g3h2j1k"
                    },
                    "type": {
                        "type": "string",
                        "example": "attendance.raw_received"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "description": "When it happened (UTC).",
                        "example": "2026-11-18T03:12:40Z"
                    },
                    "organization": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                            "id"
                        ],
                        "properties": {
                            "id": {
                                "type": "string",
                                "description": "The organization's ID (GET /api/v1/organization).",
                                "example": "01jcz5k2n4p6r8t0v2x4z6b8d0"
                            }
                        }
                    },
                    "data": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                            "attendance",
                            "previous_status"
                        ],
                        "properties": {
                            "attendance": {
                                "$ref": "#/components/schemas/Attendance"
                            },
                            "previous_status": {
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "description": "Status before this change; `null` for a new day.",
                                "example": "in_progress"
                            }
                        }
                    }
                }
            },
            "EventAttendanceCorrected": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "id",
                    "type",
                    "created_at",
                    "organization",
                    "data"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "description": "Event ID; the same as X-AR-Event-Id. Use it to ignore duplicates.",
                        "example": "01jd3m2a9b8c7d6e5f4g3h2j1k"
                    },
                    "type": {
                        "type": "string",
                        "example": "attendance.raw_received"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "description": "When it happened (UTC).",
                        "example": "2026-11-18T03:12:40Z"
                    },
                    "organization": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                            "id"
                        ],
                        "properties": {
                            "id": {
                                "type": "string",
                                "description": "The organization's ID (GET /api/v1/organization).",
                                "example": "01jcz5k2n4p6r8t0v2x4z6b8d0"
                            }
                        }
                    },
                    "data": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                            "correction",
                            "employee",
                            "note"
                        ],
                        "properties": {
                            "correction": {
                                "type": "object",
                                "additionalProperties": false,
                                "required": [
                                    "type",
                                    "date",
                                    "reason"
                                ],
                                "properties": {
                                    "type": {
                                        "type": "string",
                                        "enum": [
                                            "punch",
                                            "status"
                                        ],
                                        "example": "punch"
                                    },
                                    "date": {
                                        "type": "string",
                                        "format": "date",
                                        "example": "2026-11-17"
                                    },
                                    "punch_time": {
                                        "type": "string",
                                        "format": "date-time",
                                        "description": "Added punch (type punch).",
                                        "example": "2026-11-17T18:00:00+06:00"
                                    },
                                    "punch_state": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "status": {
                                        "type": "string",
                                        "description": "New status (type status).",
                                        "example": "present"
                                    },
                                    "reason": {
                                        "type": "string",
                                        "example": "Forgot to punch out"
                                    }
                                }
                            },
                            "employee": {
                                "$ref": "#/components/schemas/EmployeeRef"
                            },
                            "note": {
                                "type": "string",
                                "example": "The recalculated day follows as attendance.processed."
                            }
                        }
                    }
                }
            },
            "EventEmployee": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "id",
                    "type",
                    "created_at",
                    "organization",
                    "data"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "description": "Event ID; the same as X-AR-Event-Id. Use it to ignore duplicates.",
                        "example": "01jd3m2a9b8c7d6e5f4g3h2j1k"
                    },
                    "type": {
                        "type": "string",
                        "example": "attendance.raw_received"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "description": "When it happened (UTC).",
                        "example": "2026-11-18T03:12:40Z"
                    },
                    "organization": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                            "id"
                        ],
                        "properties": {
                            "id": {
                                "type": "string",
                                "description": "The organization's ID (GET /api/v1/organization).",
                                "example": "01jcz5k2n4p6r8t0v2x4z6b8d0"
                            }
                        }
                    },
                    "data": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                            "employee"
                        ],
                        "properties": {
                            "employee": {
                                "$ref": "#/components/schemas/Employee"
                            }
                        }
                    }
                }
            },
            "EventDevice": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "id",
                    "type",
                    "created_at",
                    "organization",
                    "data"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "description": "Event ID; the same as X-AR-Event-Id. Use it to ignore duplicates.",
                        "example": "01jd3m2a9b8c7d6e5f4g3h2j1k"
                    },
                    "type": {
                        "type": "string",
                        "example": "attendance.raw_received"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "description": "When it happened (UTC).",
                        "example": "2026-11-18T03:12:40Z"
                    },
                    "organization": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                            "id"
                        ],
                        "properties": {
                            "id": {
                                "type": "string",
                                "description": "The organization's ID (GET /api/v1/organization).",
                                "example": "01jcz5k2n4p6r8t0v2x4z6b8d0"
                            }
                        }
                    },
                    "data": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                            "device",
                            "reason"
                        ],
                        "properties": {
                            "device": {
                                "$ref": "#/components/schemas/Device"
                            },
                            "reason": {
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "example": "collector offline"
                            }
                        }
                    }
                }
            },
            "EventCollector": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "id",
                    "type",
                    "created_at",
                    "organization",
                    "data"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "description": "Event ID; the same as X-AR-Event-Id. Use it to ignore duplicates.",
                        "example": "01jd3m2a9b8c7d6e5f4g3h2j1k"
                    },
                    "type": {
                        "type": "string",
                        "example": "attendance.raw_received"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "description": "When it happened (UTC).",
                        "example": "2026-11-18T03:12:40Z"
                    },
                    "organization": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                            "id"
                        ],
                        "properties": {
                            "id": {
                                "type": "string",
                                "description": "The organization's ID (GET /api/v1/organization).",
                                "example": "01jcz5k2n4p6r8t0v2x4z6b8d0"
                            }
                        }
                    },
                    "data": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                            "collector"
                        ],
                        "properties": {
                            "collector": {
                                "type": "object",
                                "additionalProperties": false,
                                "required": [
                                    "id",
                                    "name",
                                    "version",
                                    "hostname",
                                    "last_heartbeat_at"
                                ],
                                "properties": {
                                    "id": {
                                        "type": "string",
                                        "example": "01jcz9a1b2c3d4e5f6g7h8j9k0"
                                    },
                                    "name": {
                                        "type": "string",
                                        "example": "Factory office PC"
                                    },
                                    "version": {
                                        "type": [
                                            "string",
                                            "null"
                                        ],
                                        "example": "1.2.3"
                                    },
                                    "hostname": {
                                        "type": [
                                            "string",
                                            "null"
                                        ],
                                        "example": "HR-PC-01"
                                    },
                                    "last_heartbeat_at": {
                                        "type": [
                                            "string",
                                            "null"
                                        ],
                                        "format": "date-time",
                                        "example": "2026-11-18T09:10:00+06:00"
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "EventSync": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "id",
                    "type",
                    "created_at",
                    "organization",
                    "data"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "description": "Event ID; the same as X-AR-Event-Id. Use it to ignore duplicates.",
                        "example": "01jd3m2a9b8c7d6e5f4g3h2j1k"
                    },
                    "type": {
                        "type": "string",
                        "example": "attendance.raw_received"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "description": "When it happened (UTC).",
                        "example": "2026-11-18T03:12:40Z"
                    },
                    "organization": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                            "id"
                        ],
                        "properties": {
                            "id": {
                                "type": "string",
                                "description": "The organization's ID (GET /api/v1/organization).",
                                "example": "01jcz5k2n4p6r8t0v2x4z6b8d0"
                            }
                        }
                    },
                    "data": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                            "command",
                            "device"
                        ],
                        "properties": {
                            "command": {
                                "type": "object",
                                "additionalProperties": false,
                                "required": [
                                    "id",
                                    "status",
                                    "requested_at",
                                    "completed_at",
                                    "message"
                                ],
                                "properties": {
                                    "id": {
                                        "type": "string",
                                        "example": "01jd0a1b2c3d4e5f6g7h8j9k0m"
                                    },
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "succeeded",
                                            "failed"
                                        ],
                                        "example": "succeeded"
                                    },
                                    "requested_at": {
                                        "type": [
                                            "string",
                                            "null"
                                        ],
                                        "format": "date-time",
                                        "example": "2026-11-18T09:00:00+06:00"
                                    },
                                    "completed_at": {
                                        "type": [
                                            "string",
                                            "null"
                                        ],
                                        "format": "date-time",
                                        "example": "2026-11-18T09:00:41+06:00"
                                    },
                                    "message": {
                                        "type": [
                                            "string",
                                            "null"
                                        ],
                                        "example": null
                                    }
                                }
                            },
                            "device": {
                                "oneOf": [
                                    {
                                        "$ref": "#/components/schemas/Device"
                                    },
                                    {
                                        "type": "null"
                                    }
                                ]
                            }
                        }
                    }
                }
            },
            "EventTest": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "id",
                    "type",
                    "created_at",
                    "organization",
                    "data"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "description": "Event ID; the same as X-AR-Event-Id. Use it to ignore duplicates.",
                        "example": "01jd3m2a9b8c7d6e5f4g3h2j1k"
                    },
                    "type": {
                        "type": "string",
                        "example": "attendance.raw_received"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "description": "When it happened (UTC).",
                        "example": "2026-11-18T03:12:40Z"
                    },
                    "organization": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                            "id"
                        ],
                        "properties": {
                            "id": {
                                "type": "string",
                                "description": "The organization's ID (GET /api/v1/organization).",
                                "example": "01jcz5k2n4p6r8t0v2x4z6b8d0"
                            }
                        }
                    },
                    "data": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                            "message",
                            "endpoint"
                        ],
                        "properties": {
                            "message": {
                                "type": "string",
                                "example": "Test event from AR ADMS Cloud. If you can read this",
                                "your endpoint works.": null
                            },
                            "endpoint": {
                                "type": "object",
                                "additionalProperties": false,
                                "required": [
                                    "id"
                                ],
                                "properties": {
                                    "id": {
                                        "type": "string",
                                        "example": "01jd3k4m6p8r0t2v4x6z8b0d2f"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}