{
    "openapi": "3.0.3",
    "info": {
        "title": "Axtara Mobile API",
        "version": "1.0.0",
        "description": "Use the worker bearer token with Authorize. These routes resolve the employee and tenant from the signed-in account; X-Tenant-ID is not required.\n\nUpload files as multipart/form-data. Allow the HTTP client to set the boundary. Personal documents, certificates, incident photos, progress photos and expense receipts have separate endpoints below.\n\nFirst-time login returns an OTP challenge. Verify the code, set a permanent password, then use the returned token to access the app. Tenant staff manage identity, employment and payment setup. Workers can view their details and update their phone and emergency contact. Login and profile reads include an informational profileIncomplete marker based on saved details. Profile completeness does not block business actions. Password setup, authentication, ownership and business validation remain enforced by the backend. Later logins use username and password. Password changes and recovery require OTP verification."
    },
    "paths": {
        "/api/v1/mobile/attendance/breaks/end": {
            "post": {
                "summary": "End your lunch break",
                "tags": [
                    "Attendance"
                ],
                "operationId": "mobileAttendanceEndBreak",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "description": "Identity and official clock times are server derived. Location is optional unless locationPolicy.locationRequired is true. For locationStatus=captured, send latitude, longitude, location_accuracy_m, locationCapturedAt and locationIsMocked. Otherwise omit coordinates. The POST rechecks policy, schedule, security and location evidence.",
                                "properties": {
                                    "latitude": {
                                        "type": "number",
                                        "minimum": -90,
                                        "maximum": 90
                                    },
                                    "longitude": {
                                        "type": "number",
                                        "minimum": -180,
                                        "maximum": 180
                                    }
                                }
                            },
                            "example": {
                                "locationStatus": "captured",
                                "latitude": 6.5,
                                "longitude": 3.4,
                                "location_accuracy_m": 10,
                                "locationCapturedAt": "2026-11-10T08:00:00+00:00",
                                "locationIsMocked": false
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Your attendance data; all clock times are server generated and include timezone offsets.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": 42,
                                                "employeeId": 3,
                                                "state": "working",
                                                "status": "active",
                                                "clockIn": "2026-11-10T08:00:00+00:00",
                                                "clockOut": null,
                                                "totalHours": null,
                                                "verificationStatus": "verified",
                                                "verificationNote": null,
                                                "isGeofenceException": false,
                                                "exceptionReason": null,
                                                "rejectionReason": null,
                                                "shift": {
                                                    "id": 9,
                                                    "title": "Day shift",
                                                    "startTime": "2026-11-10T08:00:00+00:00",
                                                    "endTime": "2026-11-10T17:00:00+00:00"
                                                },
                                                "project": {
                                                    "id": 2,
                                                    "name": "Site",
                                                    "geofence": {
                                                        "projectId": 2,
                                                        "latitude": 6.5,
                                                        "longitude": 3.4,
                                                        "radiusMeters": 100
                                                    }
                                                },
                                                "breaks": [
                                                    {
                                                        "id": 7,
                                                        "kind": "lunch",
                                                        "startedAt": "2026-11-10T12:00:00+00:00",
                                                        "endedAt": "2026-11-10T12:30:00+00:00",
                                                        "paid": false,
                                                        "durationMinutes": 30
                                                    }
                                                ],
                                                "timing": {
                                                    "basis": {
                                                        "shiftId": 9,
                                                        "shiftRevision": 1,
                                                        "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                        "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                        "opensAt": "2026-11-10T07:00:00+00:00",
                                                        "closesAt": "2026-11-10T17:00:00+00:00",
                                                        "timezone": "Africa/Lagos",
                                                        "policyVersion": "timing-v1-example",
                                                        "source": "captured",
                                                        "rules": {
                                                            "early_clock_in_minutes": 60,
                                                            "early_arrival_grace_minutes": 0,
                                                            "late_grace_minutes": 10,
                                                            "early_grace_minutes": 15,
                                                            "clock_out_grace_minutes": 60,
                                                            "require_early_arrival_reason": false,
                                                            "require_late_arrival_reason": false,
                                                            "require_early_departure_reason": false,
                                                            "require_late_departure_reason": false
                                                        }
                                                    },
                                                    "clockIn": {
                                                        "action": "clock_in",
                                                        "eligible": true,
                                                        "blockedCode": null,
                                                        "message": null,
                                                        "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                        "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                        "opensAt": "2026-11-10T07:00:00+00:00",
                                                        "closesAt": "2026-11-10T17:00:00+00:00",
                                                        "timezone": "Africa/Lagos",
                                                        "policyVersion": "timing-v1-example",
                                                        "shiftId": 9,
                                                        "shiftRevision": 1,
                                                        "recordedAt": "2026-11-10T08:00:00+00:00",
                                                        "classification": "on_time",
                                                        "minutesFromSchedule": 0,
                                                        "appliedGraceMinutes": 10,
                                                        "earlyGraceMinutes": 0,
                                                        "lateGraceMinutes": 10,
                                                        "reasonRequired": false,
                                                        "reviewRequired": false,
                                                        "reason": null,
                                                        "reasonSatisfied": true,
                                                        "basisSource": "saved"
                                                    },
                                                    "clockOut": null
                                                },
                                                "clockInReceivedAt": "2026-11-10T08:00:00+00:00",
                                                "clockOutReceivedAt": null,
                                                "recordedElapsedHours": null,
                                                "locationDecisions": {
                                                    "clockIn": {
                                                        "projectId": 2,
                                                        "expected": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "radiusMeters": 100
                                                        },
                                                        "received": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "accuracyMeters": 10
                                                        },
                                                        "distanceMeters": 0,
                                                        "outsideByMeters": 0,
                                                        "decision": "verified",
                                                        "locationStatus": "captured",
                                                        "policy": {
                                                            "geofenceRequired": true,
                                                            "locationRequired": true,
                                                            "enforceAccuracy": true,
                                                            "maxAccuracyM": 500,
                                                            "maxAgeSeconds": 120,
                                                            "clockSkewSeconds": 30,
                                                            "rejectMocked": false,
                                                            "configurationVersion": "location-v1-example"
                                                        },
                                                        "capturedAt": "2026-11-10T08:00:00+00:00",
                                                        "receivedAt": "2026-11-10T08:00:00+00:00",
                                                        "ageSeconds": 0,
                                                        "reportedMocked": false,
                                                        "flags": [],
                                                        "withinGeofence": true
                                                    },
                                                    "clockOut": null
                                                },
                                                "location": {
                                                    "projectId": 2,
                                                    "expected": {
                                                        "latitude": 6.5,
                                                        "longitude": 3.4,
                                                        "radiusMeters": 100
                                                    },
                                                    "received": {
                                                        "latitude": 6.5,
                                                        "longitude": 3.4,
                                                        "accuracyMeters": 10
                                                    },
                                                    "distanceMeters": 0,
                                                    "outsideByMeters": 0,
                                                    "decision": "verified",
                                                    "locationStatus": "captured",
                                                    "policy": {
                                                        "geofenceRequired": true,
                                                        "locationRequired": true,
                                                        "enforceAccuracy": true,
                                                        "maxAccuracyM": 500,
                                                        "maxAgeSeconds": 120,
                                                        "clockSkewSeconds": 30,
                                                        "rejectMocked": false,
                                                        "configurationVersion": "location-v1-example"
                                                    },
                                                    "capturedAt": "2026-11-10T08:00:00+00:00",
                                                    "receivedAt": "2026-11-10T08:00:00+00:00",
                                                    "ageSeconds": 0,
                                                    "reportedMocked": false,
                                                    "flags": [],
                                                    "withinGeofence": true
                                                },
                                                "attendanceDecision": "accepted"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired worker bearer token."
                    },
                    "403": {
                        "description": "Inactive worker, wrong tenant, blocked attendance module or incomplete password setup."
                    },
                    "404": {
                        "description": "Session is outside your employee scope, or no session is available for clock-out."
                    },
                    "422": {
                        "description": "Invalid input, supplied ownership fields, ineligible shift/location, disabled clock-in mode, failed PIN/device check, or lunch tracking does not apply."
                    },
                    "429": {
                        "description": "Rate limited. Retry with backoff."
                    },
                    "409": {
                        "description": "Already clocked in, invalid break transition, changed shift/timing basis, or a punch request key reused with different details. clock_out_reconciliation_required means later break activity conflicts with the clock-out receipt: refresh current/history before a new attempt."
                    }
                },
                "description": "Ends the open break on your own session using server time. Optional latitude and longitude must be supplied together and are recorded. Returns 409 if you are not clocked in or have no open break. Refresh current after a lost response before retrying.",
                "parameters": [],
                "x-generated": true
            }
        },
        "/api/v1/mobile/attendance/breaks/start": {
            "post": {
                "summary": "Start your lunch break",
                "tags": [
                    "Attendance"
                ],
                "operationId": "mobileAttendanceStartBreak",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "description": "Identity and official clock times are server derived. Location is optional unless locationPolicy.locationRequired is true. For locationStatus=captured, send latitude, longitude, location_accuracy_m, locationCapturedAt and locationIsMocked. Otherwise omit coordinates. The POST rechecks policy, schedule, security and location evidence.",
                                "properties": {
                                    "latitude": {
                                        "type": "number",
                                        "minimum": -90,
                                        "maximum": 90
                                    },
                                    "longitude": {
                                        "type": "number",
                                        "minimum": -180,
                                        "maximum": 180
                                    }
                                }
                            },
                            "example": {
                                "locationStatus": "captured",
                                "latitude": 6.5,
                                "longitude": 3.4,
                                "location_accuracy_m": 10,
                                "locationCapturedAt": "2026-11-10T08:00:00+00:00",
                                "locationIsMocked": false
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Your attendance data; all clock times are server generated and include timezone offsets.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": 42,
                                                "employeeId": 3,
                                                "state": "on_break",
                                                "status": "active",
                                                "clockIn": "2026-11-10T08:00:00+00:00",
                                                "clockOut": null,
                                                "totalHours": null,
                                                "verificationStatus": "verified",
                                                "verificationNote": null,
                                                "isGeofenceException": false,
                                                "exceptionReason": null,
                                                "rejectionReason": null,
                                                "shift": {
                                                    "id": 9,
                                                    "title": "Day shift",
                                                    "startTime": "2026-11-10T08:00:00+00:00",
                                                    "endTime": "2026-11-10T17:00:00+00:00"
                                                },
                                                "project": {
                                                    "id": 2,
                                                    "name": "Site",
                                                    "geofence": {
                                                        "projectId": 2,
                                                        "latitude": 6.5,
                                                        "longitude": 3.4,
                                                        "radiusMeters": 100
                                                    }
                                                },
                                                "breaks": [
                                                    {
                                                        "id": 7,
                                                        "kind": "lunch",
                                                        "startedAt": "2026-11-10T12:00:00+00:00",
                                                        "endedAt": null,
                                                        "paid": false,
                                                        "durationMinutes": 0
                                                    }
                                                ],
                                                "timing": {
                                                    "basis": {
                                                        "shiftId": 9,
                                                        "shiftRevision": 1,
                                                        "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                        "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                        "opensAt": "2026-11-10T07:00:00+00:00",
                                                        "closesAt": "2026-11-10T17:00:00+00:00",
                                                        "timezone": "Africa/Lagos",
                                                        "policyVersion": "timing-v1-example",
                                                        "source": "captured",
                                                        "rules": {
                                                            "early_clock_in_minutes": 60,
                                                            "early_arrival_grace_minutes": 0,
                                                            "late_grace_minutes": 10,
                                                            "early_grace_minutes": 15,
                                                            "clock_out_grace_minutes": 60,
                                                            "require_early_arrival_reason": false,
                                                            "require_late_arrival_reason": false,
                                                            "require_early_departure_reason": false,
                                                            "require_late_departure_reason": false
                                                        }
                                                    },
                                                    "clockIn": {
                                                        "action": "clock_in",
                                                        "eligible": true,
                                                        "blockedCode": null,
                                                        "message": null,
                                                        "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                        "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                        "opensAt": "2026-11-10T07:00:00+00:00",
                                                        "closesAt": "2026-11-10T17:00:00+00:00",
                                                        "timezone": "Africa/Lagos",
                                                        "policyVersion": "timing-v1-example",
                                                        "shiftId": 9,
                                                        "shiftRevision": 1,
                                                        "recordedAt": "2026-11-10T08:00:00+00:00",
                                                        "classification": "on_time",
                                                        "minutesFromSchedule": 0,
                                                        "appliedGraceMinutes": 10,
                                                        "earlyGraceMinutes": 0,
                                                        "lateGraceMinutes": 10,
                                                        "reasonRequired": false,
                                                        "reviewRequired": false,
                                                        "reason": null,
                                                        "reasonSatisfied": true,
                                                        "basisSource": "saved"
                                                    },
                                                    "clockOut": null
                                                },
                                                "clockInReceivedAt": "2026-11-10T08:00:00+00:00",
                                                "clockOutReceivedAt": null,
                                                "recordedElapsedHours": null,
                                                "locationDecisions": {
                                                    "clockIn": {
                                                        "projectId": 2,
                                                        "expected": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "radiusMeters": 100
                                                        },
                                                        "received": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "accuracyMeters": 10
                                                        },
                                                        "distanceMeters": 0,
                                                        "outsideByMeters": 0,
                                                        "decision": "verified",
                                                        "locationStatus": "captured",
                                                        "policy": {
                                                            "geofenceRequired": true,
                                                            "locationRequired": true,
                                                            "enforceAccuracy": true,
                                                            "maxAccuracyM": 500,
                                                            "maxAgeSeconds": 120,
                                                            "clockSkewSeconds": 30,
                                                            "rejectMocked": false,
                                                            "configurationVersion": "location-v1-example"
                                                        },
                                                        "capturedAt": "2026-11-10T08:00:00+00:00",
                                                        "receivedAt": "2026-11-10T08:00:00+00:00",
                                                        "ageSeconds": 0,
                                                        "reportedMocked": false,
                                                        "flags": [],
                                                        "withinGeofence": true
                                                    },
                                                    "clockOut": null
                                                },
                                                "location": {
                                                    "projectId": 2,
                                                    "expected": {
                                                        "latitude": 6.5,
                                                        "longitude": 3.4,
                                                        "radiusMeters": 100
                                                    },
                                                    "received": {
                                                        "latitude": 6.5,
                                                        "longitude": 3.4,
                                                        "accuracyMeters": 10
                                                    },
                                                    "distanceMeters": 0,
                                                    "outsideByMeters": 0,
                                                    "decision": "verified",
                                                    "locationStatus": "captured",
                                                    "policy": {
                                                        "geofenceRequired": true,
                                                        "locationRequired": true,
                                                        "enforceAccuracy": true,
                                                        "maxAccuracyM": 500,
                                                        "maxAgeSeconds": 120,
                                                        "clockSkewSeconds": 30,
                                                        "rejectMocked": false,
                                                        "configurationVersion": "location-v1-example"
                                                    },
                                                    "capturedAt": "2026-11-10T08:00:00+00:00",
                                                    "receivedAt": "2026-11-10T08:00:00+00:00",
                                                    "ageSeconds": 0,
                                                    "reportedMocked": false,
                                                    "flags": [],
                                                    "withinGeofence": true
                                                },
                                                "attendanceDecision": "accepted"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired worker bearer token."
                    },
                    "403": {
                        "description": "Inactive worker, wrong tenant, blocked attendance module or incomplete password setup."
                    },
                    "404": {
                        "description": "Session is outside your employee scope, or no session is available for clock-out."
                    },
                    "422": {
                        "description": "Invalid input, supplied ownership fields, ineligible shift/location, disabled clock-in mode, failed PIN/device check, or lunch tracking does not apply."
                    },
                    "429": {
                        "description": "Rate limited. Retry with backoff."
                    },
                    "409": {
                        "description": "Already clocked in, invalid break transition, changed shift/timing basis, or a punch request key reused with different details. clock_out_reconciliation_required means later break activity conflicts with the clock-out receipt: refresh current/history before a new attempt."
                    }
                },
                "description": "Starts a break on your own open session using the applicable tenant lunch policy. Optional latitude and longitude must be supplied together and are recorded. Paid status is set by policy. Returns 201, 409 when not clocked in or already on break, and 422 when lunch tracking does not apply. Refresh current after a lost response before retrying.",
                "parameters": [],
                "x-generated": true
            }
        },
        "/api/v1/mobile/attendance/captures": {
            "post": {
                "summary": "Start a facial attendance capture",
                "tags": [
                    "Attendance"
                ],
                "operationId": "faceAttendanceCapture",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "action": {
                                        "type": "string",
                                        "enum": [
                                            "clock_in",
                                            "clock_out"
                                        ]
                                    }
                                },
                                "required": [
                                    "action"
                                ]
                            },
                            "example": {
                                "action": "clock_in"
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Private enrollment or capture metadata. No vectors, templates, image paths or similarity scores are returned.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "865de084-a91d-4edc-afcb-7059b9d229e0",
                                                "action": "clock_in",
                                                "status": "issued",
                                                "expires_at": "2026-11-10T08:03:00Z",
                                                "photo_available": false,
                                                "photo_deleted_at": null
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired bearer token."
                    },
                    "403": {
                        "description": "Worker/HR/attendance permission required; reviewers cannot approve their own enrollment."
                    },
                    "404": {
                        "description": "The record is outside your employee or tenant scope."
                    },
                    "409": {
                        "description": "Pending enrollment already exists, already reviewed, capture expired/used, or photo binding changed."
                    },
                    "422": {
                        "description": "Invalid JPEG, image count/size, action or enrollment quality."
                    },
                    "429": {
                        "description": "Capture/enrollment rate limit reached."
                    },
                    "503": {
                        "description": "Upload scanner, enrollment processing or enrollment encryption unavailable. A sidecar outage during attendance photo processing instead produces a ready capture requiring human review."
                    }
                },
                "description": "Send action=clock_in or clock_out. Returns an owned UUID capture with a three-minute expires_at. Upload the final JPEG to its photo endpoint, then pass captureId to the matching clock action before expiry. Issuing a capture does not record attendance.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/attendance/captures/{capture}": {
            "get": {
                "summary": "Check your facial capture status",
                "tags": [
                    "Attendance"
                ],
                "operationId": "faceAttendanceCaptureStatus",
                "parameters": [
                    {
                        "name": "capture",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Private enrollment or capture metadata. No vectors, templates, image paths or similarity scores are returned.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "865de084-a91d-4edc-afcb-7059b9d229e0",
                                                "action": "clock_in",
                                                "status": "ready",
                                                "expires_at": "2026-11-10T08:03:00Z",
                                                "photo_available": true,
                                                "photo_deleted_at": null,
                                                "reason": "review_only",
                                                "consumed_at": null
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired bearer token."
                    },
                    "403": {
                        "description": "Worker/HR/attendance permission required; reviewers cannot approve their own enrollment."
                    },
                    "404": {
                        "description": "The record is outside your employee or tenant scope."
                    },
                    "409": {
                        "description": "Pending enrollment already exists, already reviewed, capture expired/used, or photo binding changed."
                    },
                    "422": {
                        "description": "Invalid JPEG, image count/size, action or enrollment quality."
                    },
                    "429": {
                        "description": "Capture/enrollment rate limit reached."
                    },
                    "503": {
                        "description": "Upload scanner, enrollment processing or enrollment encryption unavailable. A sidecar outage during attendance photo processing instead produces a ready capture requiring human review."
                    }
                },
                "description": "Returns only your capture metadata after a lost upload response: issued, processing, ready or consumed, plus expires_at. It does not record attendance. If processing persists for 45 seconds, retry the exact same photo and livenessSignal before capture expiry; the retry moves interrupted processing to ready for human review. Expired captures require a new capture. Another employee or tenant returns 404.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/attendance/captures/{capture}/photo": {
            "post": {
                "summary": "Bind a selfie to your clock capture",
                "tags": [
                    "Attendance"
                ],
                "operationId": "faceAttendanceUpload",
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "photo": {
                                        "type": "string",
                                        "format": "binary",
                                        "description": "Final JPEG selfie, at most 5 MiB."
                                    },
                                    "livenessSignal": {
                                        "type": "boolean",
                                        "description": "Optional untrusted app challenge result; never proof of liveness."
                                    }
                                },
                                "required": [
                                    "photo"
                                ]
                            },
                            "example": {
                                "photo": "(binary JPEG selfie)",
                                "livenessSignal": true
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "capture",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Private enrollment or capture metadata. No vectors, templates, image paths or similarity scores are returned.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "865de084-a91d-4edc-afcb-7059b9d229e0",
                                                "action": "clock_in",
                                                "status": "ready",
                                                "expires_at": "2026-11-10T08:03:00Z",
                                                "photo_available": true,
                                                "photo_deleted_at": null,
                                                "reason": "review_only",
                                                "liveness_signal": true
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired bearer token."
                    },
                    "403": {
                        "description": "Worker/HR/attendance permission required; reviewers cannot approve their own enrollment."
                    },
                    "404": {
                        "description": "The record is outside your employee or tenant scope."
                    },
                    "409": {
                        "description": "Pending enrollment already exists, already reviewed, capture expired/used, or photo binding changed."
                    },
                    "422": {
                        "description": "Invalid JPEG, image count/size, action or enrollment quality."
                    },
                    "429": {
                        "description": "Capture/enrollment rate limit reached."
                    },
                    "503": {
                        "description": "Upload scanner, enrollment processing or enrollment encryption unavailable. A sidecar outage during attendance photo processing instead produces a ready capture requiring human review."
                    }
                },
                "description": "Upload photo as multipart JPEG, up to 5 MiB subject to server limits; optional livenessSignal is a boolean app observation, not proof. The first upload binds the exact photo hash to this capture. Identical photo/signal retries return the saved result; a changed photo/signal returns 409. Processing returns 409 while active; an identical retry after 45 seconds recovers interrupted processing as ready with sidecar_interrupted, requiring human review. Sidecar quality failures, outages or absent enrollment produce a ready capture requiring human review. No attendance is recorded yet.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/attendance/clock-in": {
            "post": {
                "summary": "Clock in using server-owned decisions",
                "tags": [
                    "Attendance"
                ],
                "operationId": "mobileAttendanceClockIn",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "description": "Identity and official clock times are server derived. Location is optional unless locationPolicy.locationRequired is true. For locationStatus=captured, send latitude, longitude, location_accuracy_m, locationCapturedAt and locationIsMocked. Otherwise omit coordinates. The POST rechecks policy, schedule, security and location evidence.",
                                "properties": {
                                    "latitude": {
                                        "type": "number",
                                        "minimum": -90,
                                        "maximum": 90
                                    },
                                    "longitude": {
                                        "type": "number",
                                        "minimum": -180,
                                        "maximum": 180
                                    },
                                    "location_accuracy_m": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 100000,
                                        "description": "Device-reported accuracy in metres. Enforced only by the effective locationPolicy."
                                    },
                                    "shift_id": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "description": "An eligible published shift assigned to you."
                                    },
                                    "shiftRevision": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "description": "Optional expected schedule revision. Stale revision returns 409."
                                    },
                                    "mode": {
                                        "type": "string",
                                        "enum": [
                                            "account",
                                            "employee_number",
                                            "facial"
                                        ]
                                    },
                                    "pin": {
                                        "type": "string",
                                        "description": "Required for employee-number punches when policy requires a PIN."
                                    },
                                    "captureId": {
                                        "type": "string",
                                        "format": "uuid",
                                        "description": "Required for facial punches. Issue an action-bound capture and upload its photo first."
                                    },
                                    "locationStatus": {
                                        "type": "string",
                                        "enum": [
                                            "captured",
                                            "permission_denied",
                                            "services_disabled",
                                            "timeout",
                                            "unavailable"
                                        ]
                                    },
                                    "locationCapturedAt": {
                                        "type": "string",
                                        "format": "date-time",
                                        "description": "Device evidence timestamp with offset; official attendance uses server receipt time."
                                    },
                                    "locationIsMocked": {
                                        "type": "boolean",
                                        "description": "Untrusted OS-reported mock-location flag."
                                    }
                                }
                            },
                            "example": {
                                "locationStatus": "captured",
                                "latitude": 6.5,
                                "longitude": 3.4,
                                "location_accuracy_m": 10,
                                "locationCapturedAt": "2026-11-10T08:00:00+00:00",
                                "locationIsMocked": false
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Your attendance data; all clock times are server generated and include timezone offsets.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": 42,
                                                "employeeId": 3,
                                                "state": "working",
                                                "status": "active",
                                                "clockIn": "2026-11-10T08:00:00+00:00",
                                                "clockOut": null,
                                                "totalHours": null,
                                                "verificationStatus": "verified",
                                                "verificationNote": null,
                                                "isGeofenceException": false,
                                                "exceptionReason": null,
                                                "rejectionReason": null,
                                                "shift": {
                                                    "id": 9,
                                                    "title": "Day shift",
                                                    "startTime": "2026-11-10T08:00:00+00:00",
                                                    "endTime": "2026-11-10T17:00:00+00:00"
                                                },
                                                "project": {
                                                    "id": 2,
                                                    "name": "Site",
                                                    "geofence": {
                                                        "projectId": 2,
                                                        "latitude": 6.5,
                                                        "longitude": 3.4,
                                                        "radiusMeters": 100
                                                    }
                                                },
                                                "breaks": [],
                                                "timing": {
                                                    "basis": {
                                                        "shiftId": 9,
                                                        "shiftRevision": 1,
                                                        "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                        "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                        "opensAt": "2026-11-10T07:00:00+00:00",
                                                        "closesAt": "2026-11-10T17:00:00+00:00",
                                                        "timezone": "Africa/Lagos",
                                                        "policyVersion": "timing-v1-example",
                                                        "source": "captured",
                                                        "rules": {
                                                            "early_clock_in_minutes": 60,
                                                            "early_arrival_grace_minutes": 0,
                                                            "late_grace_minutes": 10,
                                                            "early_grace_minutes": 15,
                                                            "clock_out_grace_minutes": 60,
                                                            "require_early_arrival_reason": false,
                                                            "require_late_arrival_reason": false,
                                                            "require_early_departure_reason": false,
                                                            "require_late_departure_reason": false
                                                        }
                                                    },
                                                    "clockIn": {
                                                        "action": "clock_in",
                                                        "eligible": true,
                                                        "blockedCode": null,
                                                        "message": null,
                                                        "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                        "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                        "opensAt": "2026-11-10T07:00:00+00:00",
                                                        "closesAt": "2026-11-10T17:00:00+00:00",
                                                        "timezone": "Africa/Lagos",
                                                        "policyVersion": "timing-v1-example",
                                                        "shiftId": 9,
                                                        "shiftRevision": 1,
                                                        "recordedAt": "2026-11-10T08:00:00+00:00",
                                                        "classification": "on_time",
                                                        "minutesFromSchedule": 0,
                                                        "appliedGraceMinutes": 10,
                                                        "earlyGraceMinutes": 0,
                                                        "lateGraceMinutes": 10,
                                                        "reasonRequired": false,
                                                        "reviewRequired": false,
                                                        "reason": null,
                                                        "reasonSatisfied": true,
                                                        "basisSource": "saved"
                                                    },
                                                    "clockOut": null
                                                },
                                                "clockInReceivedAt": "2026-11-10T08:00:00+00:00",
                                                "clockOutReceivedAt": null,
                                                "recordedElapsedHours": null,
                                                "locationDecisions": {
                                                    "clockIn": {
                                                        "projectId": 2,
                                                        "expected": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "radiusMeters": 100
                                                        },
                                                        "received": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "accuracyMeters": 10
                                                        },
                                                        "distanceMeters": 0,
                                                        "outsideByMeters": 0,
                                                        "decision": "verified",
                                                        "locationStatus": "captured",
                                                        "policy": {
                                                            "geofenceRequired": true,
                                                            "locationRequired": true,
                                                            "enforceAccuracy": true,
                                                            "maxAccuracyM": 500,
                                                            "maxAgeSeconds": 120,
                                                            "clockSkewSeconds": 30,
                                                            "rejectMocked": false,
                                                            "configurationVersion": "location-v1-example"
                                                        },
                                                        "capturedAt": "2026-11-10T08:00:00+00:00",
                                                        "receivedAt": "2026-11-10T08:00:00+00:00",
                                                        "ageSeconds": 0,
                                                        "reportedMocked": false,
                                                        "flags": [],
                                                        "withinGeofence": true
                                                    },
                                                    "clockOut": null
                                                },
                                                "location": {
                                                    "projectId": 2,
                                                    "expected": {
                                                        "latitude": 6.5,
                                                        "longitude": 3.4,
                                                        "radiusMeters": 100
                                                    },
                                                    "received": {
                                                        "latitude": 6.5,
                                                        "longitude": 3.4,
                                                        "accuracyMeters": 10
                                                    },
                                                    "distanceMeters": 0,
                                                    "outsideByMeters": 0,
                                                    "decision": "verified",
                                                    "locationStatus": "captured",
                                                    "policy": {
                                                        "geofenceRequired": true,
                                                        "locationRequired": true,
                                                        "enforceAccuracy": true,
                                                        "maxAccuracyM": 500,
                                                        "maxAgeSeconds": 120,
                                                        "clockSkewSeconds": 30,
                                                        "rejectMocked": false,
                                                        "configurationVersion": "location-v1-example"
                                                    },
                                                    "capturedAt": "2026-11-10T08:00:00+00:00",
                                                    "receivedAt": "2026-11-10T08:00:00+00:00",
                                                    "ageSeconds": 0,
                                                    "reportedMocked": false,
                                                    "flags": [],
                                                    "withinGeofence": true
                                                },
                                                "attendanceDecision": "accepted"
                                            },
                                            "replayed": false
                                        }
                                    },
                                    "facialPending": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": 42,
                                                "employeeId": 3,
                                                "state": "working",
                                                "status": "active",
                                                "clockIn": "2026-11-10T08:00:00+00:00",
                                                "clockOut": null,
                                                "totalHours": null,
                                                "verificationStatus": "pending",
                                                "verificationNote": null,
                                                "isGeofenceException": false,
                                                "exceptionReason": null,
                                                "rejectionReason": null,
                                                "shift": {
                                                    "id": 9,
                                                    "title": "Day shift",
                                                    "startTime": "2026-11-10T08:00:00+00:00",
                                                    "endTime": "2026-11-10T17:00:00+00:00"
                                                },
                                                "project": {
                                                    "id": 2,
                                                    "name": "Site",
                                                    "geofence": {
                                                        "projectId": 2,
                                                        "latitude": 6.5,
                                                        "longitude": 3.4,
                                                        "radiusMeters": 100
                                                    }
                                                },
                                                "breaks": [],
                                                "timing": {
                                                    "basis": {
                                                        "shiftId": 9,
                                                        "shiftRevision": 1,
                                                        "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                        "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                        "opensAt": "2026-11-10T07:00:00+00:00",
                                                        "closesAt": "2026-11-10T17:00:00+00:00",
                                                        "timezone": "Africa/Lagos",
                                                        "policyVersion": "timing-v1-example",
                                                        "source": "captured",
                                                        "rules": {
                                                            "early_clock_in_minutes": 60,
                                                            "early_arrival_grace_minutes": 0,
                                                            "late_grace_minutes": 10,
                                                            "early_grace_minutes": 15,
                                                            "clock_out_grace_minutes": 60,
                                                            "require_early_arrival_reason": false,
                                                            "require_late_arrival_reason": false,
                                                            "require_early_departure_reason": false,
                                                            "require_late_departure_reason": false
                                                        }
                                                    },
                                                    "clockIn": {
                                                        "action": "clock_in",
                                                        "eligible": true,
                                                        "blockedCode": null,
                                                        "message": null,
                                                        "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                        "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                        "opensAt": "2026-11-10T07:00:00+00:00",
                                                        "closesAt": "2026-11-10T17:00:00+00:00",
                                                        "timezone": "Africa/Lagos",
                                                        "policyVersion": "timing-v1-example",
                                                        "shiftId": 9,
                                                        "shiftRevision": 1,
                                                        "recordedAt": "2026-11-10T08:00:00+00:00",
                                                        "classification": "on_time",
                                                        "minutesFromSchedule": 0,
                                                        "appliedGraceMinutes": 10,
                                                        "earlyGraceMinutes": 0,
                                                        "lateGraceMinutes": 10,
                                                        "reasonRequired": false,
                                                        "reviewRequired": false,
                                                        "reason": null,
                                                        "reasonSatisfied": true,
                                                        "basisSource": "saved"
                                                    },
                                                    "clockOut": null
                                                },
                                                "clockInReceivedAt": "2026-11-10T08:00:00+00:00",
                                                "clockOutReceivedAt": null,
                                                "recordedElapsedHours": null,
                                                "locationDecisions": {
                                                    "clockIn": {
                                                        "projectId": 2,
                                                        "expected": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "radiusMeters": 100
                                                        },
                                                        "received": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "accuracyMeters": 10
                                                        },
                                                        "distanceMeters": 0,
                                                        "outsideByMeters": 0,
                                                        "decision": "verified",
                                                        "locationStatus": "captured",
                                                        "policy": {
                                                            "geofenceRequired": true,
                                                            "locationRequired": true,
                                                            "enforceAccuracy": true,
                                                            "maxAccuracyM": 500,
                                                            "maxAgeSeconds": 120,
                                                            "clockSkewSeconds": 30,
                                                            "rejectMocked": false,
                                                            "configurationVersion": "location-v1-example"
                                                        },
                                                        "capturedAt": "2026-11-10T08:00:00+00:00",
                                                        "receivedAt": "2026-11-10T08:00:00+00:00",
                                                        "ageSeconds": 0,
                                                        "reportedMocked": false,
                                                        "flags": [],
                                                        "withinGeofence": true
                                                    },
                                                    "clockOut": null
                                                },
                                                "location": {
                                                    "projectId": 2,
                                                    "expected": {
                                                        "latitude": 6.5,
                                                        "longitude": 3.4,
                                                        "radiusMeters": 100
                                                    },
                                                    "received": {
                                                        "latitude": 6.5,
                                                        "longitude": 3.4,
                                                        "accuracyMeters": 10
                                                    },
                                                    "distanceMeters": 0,
                                                    "outsideByMeters": 0,
                                                    "decision": "verified",
                                                    "locationStatus": "captured",
                                                    "policy": {
                                                        "geofenceRequired": true,
                                                        "locationRequired": true,
                                                        "enforceAccuracy": true,
                                                        "maxAccuracyM": 500,
                                                        "maxAgeSeconds": 120,
                                                        "clockSkewSeconds": 30,
                                                        "rejectMocked": false,
                                                        "configurationVersion": "location-v1-example"
                                                    },
                                                    "capturedAt": "2026-11-10T08:00:00+00:00",
                                                    "receivedAt": "2026-11-10T08:00:00+00:00",
                                                    "ageSeconds": 0,
                                                    "reportedMocked": false,
                                                    "flags": [],
                                                    "withinGeofence": true
                                                },
                                                "attendanceDecision": "review_required"
                                            },
                                            "replayed": false
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired worker bearer token."
                    },
                    "403": {
                        "description": "Inactive worker, wrong tenant, blocked attendance module or incomplete password setup."
                    },
                    "404": {
                        "description": "Session is outside your employee scope, or no session is available for clock-out."
                    },
                    "422": {
                        "description": "Invalid attendance input or business rule. A configured project fence always requires inside coordinates.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "geofence": {
                                        "value": {
                                            "message": "Clocking requires a verified location inside this project geofence.",
                                            "code": "outside_geofence",
                                            "timing": {
                                                "action": "clock_in",
                                                "eligible": true,
                                                "blockedCode": null,
                                                "message": null,
                                                "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                "opensAt": "2026-11-10T07:00:00+00:00",
                                                "closesAt": "2026-11-10T17:00:00+00:00",
                                                "timezone": "Africa/Lagos",
                                                "policyVersion": "timing-v1-example",
                                                "shiftId": 9,
                                                "shiftRevision": 1,
                                                "recordedAt": "2026-11-10T08:00:00+00:00",
                                                "classification": "on_time",
                                                "minutesFromSchedule": 0,
                                                "appliedGraceMinutes": 10,
                                                "earlyGraceMinutes": 0,
                                                "lateGraceMinutes": 10,
                                                "reasonRequired": false,
                                                "reviewRequired": false
                                            },
                                            "location": {
                                                "projectId": 2,
                                                "expected": {
                                                    "latitude": 6.5,
                                                    "longitude": 3.4,
                                                    "radiusMeters": 100
                                                },
                                                "received": {
                                                    "latitude": 7,
                                                    "longitude": 3.4,
                                                    "accuracyMeters": 10
                                                },
                                                "distanceMeters": 55597.46,
                                                "outsideByMeters": 55497.46,
                                                "decision": "rejected",
                                                "locationStatus": "captured",
                                                "policy": {
                                                    "geofenceRequired": true,
                                                    "locationRequired": true,
                                                    "enforceAccuracy": true,
                                                    "maxAccuracyM": 500,
                                                    "maxAgeSeconds": 120,
                                                    "clockSkewSeconds": 30,
                                                    "rejectMocked": false,
                                                    "configurationVersion": "location-v1-example"
                                                },
                                                "capturedAt": "2026-11-10T08:00:00+00:00",
                                                "receivedAt": "2026-11-10T08:00:00+00:00",
                                                "ageSeconds": 0,
                                                "reportedMocked": false,
                                                "flags": [],
                                                "withinGeofence": false
                                            }
                                        }
                                    },
                                    "windowClosed": {
                                        "value": {
                                            "message": "Outside the allowed clock-in window for this shift.",
                                            "code": "clock_in_window_closed",
                                            "timing": {
                                                "action": "clock_in",
                                                "eligible": false,
                                                "blockedCode": "clock_in_window_closed",
                                                "message": "The clock-in window has closed.",
                                                "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                "opensAt": "2026-11-10T07:00:00+00:00",
                                                "closesAt": "2026-11-10T17:00:00+00:00",
                                                "timezone": "Africa/Lagos",
                                                "policyVersion": "timing-v1-example",
                                                "shiftId": 9,
                                                "shiftRevision": 1,
                                                "recordedAt": "2026-11-10T17:00:00+00:00",
                                                "classification": "late",
                                                "minutesFromSchedule": 540,
                                                "appliedGraceMinutes": 10,
                                                "earlyGraceMinutes": 0,
                                                "lateGraceMinutes": 10,
                                                "reasonRequired": false,
                                                "reviewRequired": true
                                            }
                                        }
                                    },
                                    "windowNotOpen": {
                                        "value": {
                                            "message": "Outside the allowed clock-in window for this shift.",
                                            "code": "clock_in_too_early",
                                            "timing": {
                                                "action": "clock_in",
                                                "eligible": false,
                                                "blockedCode": "clock_in_too_early",
                                                "message": "The clock-in window has not opened yet.",
                                                "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                "opensAt": "2026-11-10T07:00:00+00:00",
                                                "closesAt": "2026-11-10T17:00:00+00:00",
                                                "timezone": "Africa/Lagos",
                                                "policyVersion": "timing-v1-example",
                                                "shiftId": 9,
                                                "shiftRevision": 1,
                                                "recordedAt": "2026-11-10T06:59:59+00:00",
                                                "classification": "early",
                                                "minutesFromSchedule": -60.0167,
                                                "appliedGraceMinutes": 0,
                                                "earlyGraceMinutes": 0,
                                                "lateGraceMinutes": 10,
                                                "reasonRequired": false,
                                                "reviewRequired": true
                                            }
                                        }
                                    },
                                    "location_required": {
                                        "value": {
                                            "message": "Location evidence does not satisfy the attendance policy.",
                                            "code": "location_required",
                                            "timing": {
                                                "action": "clock_in",
                                                "eligible": true,
                                                "blockedCode": null,
                                                "message": null,
                                                "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                "opensAt": "2026-11-10T07:00:00+00:00",
                                                "closesAt": "2026-11-10T17:00:00+00:00",
                                                "timezone": "Africa/Lagos",
                                                "policyVersion": "timing-v1-example",
                                                "shiftId": 9,
                                                "shiftRevision": 1,
                                                "recordedAt": "2026-11-10T08:00:00+00:00",
                                                "classification": "on_time",
                                                "minutesFromSchedule": 0,
                                                "appliedGraceMinutes": 10,
                                                "earlyGraceMinutes": 0,
                                                "lateGraceMinutes": 10,
                                                "reasonRequired": false,
                                                "reviewRequired": false
                                            },
                                            "location": {
                                                "projectId": 2,
                                                "expected": {
                                                    "latitude": 6.5,
                                                    "longitude": 3.4,
                                                    "radiusMeters": 100
                                                },
                                                "received": {
                                                    "latitude": null,
                                                    "longitude": null,
                                                    "accuracyMeters": null
                                                },
                                                "distanceMeters": null,
                                                "outsideByMeters": null,
                                                "decision": "rejected",
                                                "locationStatus": null,
                                                "policy": {
                                                    "geofenceRequired": true,
                                                    "locationRequired": true,
                                                    "enforceAccuracy": true,
                                                    "maxAccuracyM": 500,
                                                    "maxAgeSeconds": 120,
                                                    "clockSkewSeconds": 30,
                                                    "rejectMocked": false,
                                                    "configurationVersion": "location-v1-example"
                                                },
                                                "capturedAt": null,
                                                "receivedAt": "2026-11-10T08:00:00+00:00",
                                                "ageSeconds": null,
                                                "reportedMocked": false,
                                                "flags": [],
                                                "withinGeofence": null
                                            }
                                        }
                                    },
                                    "location_permission_denied": {
                                        "value": {
                                            "message": "Location evidence does not satisfy the attendance policy.",
                                            "code": "location_permission_denied",
                                            "timing": {
                                                "action": "clock_in",
                                                "eligible": true,
                                                "blockedCode": null,
                                                "message": null,
                                                "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                "opensAt": "2026-11-10T07:00:00+00:00",
                                                "closesAt": "2026-11-10T17:00:00+00:00",
                                                "timezone": "Africa/Lagos",
                                                "policyVersion": "timing-v1-example",
                                                "shiftId": 9,
                                                "shiftRevision": 1,
                                                "recordedAt": "2026-11-10T08:00:00+00:00",
                                                "classification": "on_time",
                                                "minutesFromSchedule": 0,
                                                "appliedGraceMinutes": 10,
                                                "earlyGraceMinutes": 0,
                                                "lateGraceMinutes": 10,
                                                "reasonRequired": false,
                                                "reviewRequired": false
                                            },
                                            "location": {
                                                "projectId": 2,
                                                "expected": {
                                                    "latitude": 6.5,
                                                    "longitude": 3.4,
                                                    "radiusMeters": 100
                                                },
                                                "received": {
                                                    "latitude": null,
                                                    "longitude": null,
                                                    "accuracyMeters": null
                                                },
                                                "distanceMeters": null,
                                                "outsideByMeters": null,
                                                "decision": "rejected",
                                                "locationStatus": "permission_denied",
                                                "policy": {
                                                    "geofenceRequired": true,
                                                    "locationRequired": true,
                                                    "enforceAccuracy": true,
                                                    "maxAccuracyM": 500,
                                                    "maxAgeSeconds": 120,
                                                    "clockSkewSeconds": 30,
                                                    "rejectMocked": false,
                                                    "configurationVersion": "location-v1-example"
                                                },
                                                "capturedAt": null,
                                                "receivedAt": "2026-11-10T08:00:00+00:00",
                                                "ageSeconds": null,
                                                "reportedMocked": false,
                                                "flags": [],
                                                "withinGeofence": null
                                            }
                                        }
                                    },
                                    "location_services_disabled": {
                                        "value": {
                                            "message": "Location evidence does not satisfy the attendance policy.",
                                            "code": "location_services_disabled",
                                            "timing": {
                                                "action": "clock_in",
                                                "eligible": true,
                                                "blockedCode": null,
                                                "message": null,
                                                "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                "opensAt": "2026-11-10T07:00:00+00:00",
                                                "closesAt": "2026-11-10T17:00:00+00:00",
                                                "timezone": "Africa/Lagos",
                                                "policyVersion": "timing-v1-example",
                                                "shiftId": 9,
                                                "shiftRevision": 1,
                                                "recordedAt": "2026-11-10T08:00:00+00:00",
                                                "classification": "on_time",
                                                "minutesFromSchedule": 0,
                                                "appliedGraceMinutes": 10,
                                                "earlyGraceMinutes": 0,
                                                "lateGraceMinutes": 10,
                                                "reasonRequired": false,
                                                "reviewRequired": false
                                            },
                                            "location": {
                                                "projectId": 2,
                                                "expected": {
                                                    "latitude": 6.5,
                                                    "longitude": 3.4,
                                                    "radiusMeters": 100
                                                },
                                                "received": {
                                                    "latitude": null,
                                                    "longitude": null,
                                                    "accuracyMeters": null
                                                },
                                                "distanceMeters": null,
                                                "outsideByMeters": null,
                                                "decision": "rejected",
                                                "locationStatus": "services_disabled",
                                                "policy": {
                                                    "geofenceRequired": true,
                                                    "locationRequired": true,
                                                    "enforceAccuracy": true,
                                                    "maxAccuracyM": 500,
                                                    "maxAgeSeconds": 120,
                                                    "clockSkewSeconds": 30,
                                                    "rejectMocked": false,
                                                    "configurationVersion": "location-v1-example"
                                                },
                                                "capturedAt": null,
                                                "receivedAt": "2026-11-10T08:00:00+00:00",
                                                "ageSeconds": null,
                                                "reportedMocked": false,
                                                "flags": [],
                                                "withinGeofence": null
                                            }
                                        }
                                    },
                                    "location_timeout": {
                                        "value": {
                                            "message": "Location evidence does not satisfy the attendance policy.",
                                            "code": "location_timeout",
                                            "timing": {
                                                "action": "clock_in",
                                                "eligible": true,
                                                "blockedCode": null,
                                                "message": null,
                                                "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                "opensAt": "2026-11-10T07:00:00+00:00",
                                                "closesAt": "2026-11-10T17:00:00+00:00",
                                                "timezone": "Africa/Lagos",
                                                "policyVersion": "timing-v1-example",
                                                "shiftId": 9,
                                                "shiftRevision": 1,
                                                "recordedAt": "2026-11-10T08:00:00+00:00",
                                                "classification": "on_time",
                                                "minutesFromSchedule": 0,
                                                "appliedGraceMinutes": 10,
                                                "earlyGraceMinutes": 0,
                                                "lateGraceMinutes": 10,
                                                "reasonRequired": false,
                                                "reviewRequired": false
                                            },
                                            "location": {
                                                "projectId": 2,
                                                "expected": {
                                                    "latitude": 6.5,
                                                    "longitude": 3.4,
                                                    "radiusMeters": 100
                                                },
                                                "received": {
                                                    "latitude": null,
                                                    "longitude": null,
                                                    "accuracyMeters": null
                                                },
                                                "distanceMeters": null,
                                                "outsideByMeters": null,
                                                "decision": "rejected",
                                                "locationStatus": "timeout",
                                                "policy": {
                                                    "geofenceRequired": true,
                                                    "locationRequired": true,
                                                    "enforceAccuracy": true,
                                                    "maxAccuracyM": 500,
                                                    "maxAgeSeconds": 120,
                                                    "clockSkewSeconds": 30,
                                                    "rejectMocked": false,
                                                    "configurationVersion": "location-v1-example"
                                                },
                                                "capturedAt": null,
                                                "receivedAt": "2026-11-10T08:00:00+00:00",
                                                "ageSeconds": null,
                                                "reportedMocked": false,
                                                "flags": [],
                                                "withinGeofence": null
                                            }
                                        }
                                    },
                                    "location_unavailable": {
                                        "value": {
                                            "message": "Location evidence does not satisfy the attendance policy.",
                                            "code": "location_unavailable",
                                            "timing": {
                                                "action": "clock_in",
                                                "eligible": true,
                                                "blockedCode": null,
                                                "message": null,
                                                "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                "opensAt": "2026-11-10T07:00:00+00:00",
                                                "closesAt": "2026-11-10T17:00:00+00:00",
                                                "timezone": "Africa/Lagos",
                                                "policyVersion": "timing-v1-example",
                                                "shiftId": 9,
                                                "shiftRevision": 1,
                                                "recordedAt": "2026-11-10T08:00:00+00:00",
                                                "classification": "on_time",
                                                "minutesFromSchedule": 0,
                                                "appliedGraceMinutes": 10,
                                                "earlyGraceMinutes": 0,
                                                "lateGraceMinutes": 10,
                                                "reasonRequired": false,
                                                "reviewRequired": false
                                            },
                                            "location": {
                                                "projectId": 2,
                                                "expected": {
                                                    "latitude": 6.5,
                                                    "longitude": 3.4,
                                                    "radiusMeters": 100
                                                },
                                                "received": {
                                                    "latitude": null,
                                                    "longitude": null,
                                                    "accuracyMeters": null
                                                },
                                                "distanceMeters": null,
                                                "outsideByMeters": null,
                                                "decision": "rejected",
                                                "locationStatus": "unavailable",
                                                "policy": {
                                                    "geofenceRequired": true,
                                                    "locationRequired": true,
                                                    "enforceAccuracy": true,
                                                    "maxAccuracyM": 500,
                                                    "maxAgeSeconds": 120,
                                                    "clockSkewSeconds": 30,
                                                    "rejectMocked": false,
                                                    "configurationVersion": "location-v1-example"
                                                },
                                                "capturedAt": null,
                                                "receivedAt": "2026-11-10T08:00:00+00:00",
                                                "ageSeconds": null,
                                                "reportedMocked": false,
                                                "flags": [],
                                                "withinGeofence": null
                                            }
                                        }
                                    },
                                    "location_stale": {
                                        "value": {
                                            "message": "Location evidence does not satisfy the attendance policy.",
                                            "code": "location_stale",
                                            "timing": {
                                                "action": "clock_in",
                                                "eligible": true,
                                                "blockedCode": null,
                                                "message": null,
                                                "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                "opensAt": "2026-11-10T07:00:00+00:00",
                                                "closesAt": "2026-11-10T17:00:00+00:00",
                                                "timezone": "Africa/Lagos",
                                                "policyVersion": "timing-v1-example",
                                                "shiftId": 9,
                                                "shiftRevision": 1,
                                                "recordedAt": "2026-11-10T08:00:00+00:00",
                                                "classification": "on_time",
                                                "minutesFromSchedule": 0,
                                                "appliedGraceMinutes": 10,
                                                "earlyGraceMinutes": 0,
                                                "lateGraceMinutes": 10,
                                                "reasonRequired": false,
                                                "reviewRequired": false
                                            },
                                            "location": {
                                                "projectId": 2,
                                                "expected": {
                                                    "latitude": 6.5,
                                                    "longitude": 3.4,
                                                    "radiusMeters": 100
                                                },
                                                "received": {
                                                    "latitude": 6.5,
                                                    "longitude": 3.4,
                                                    "accuracyMeters": 10
                                                },
                                                "distanceMeters": 0,
                                                "outsideByMeters": 0,
                                                "decision": "rejected",
                                                "locationStatus": "captured",
                                                "policy": {
                                                    "geofenceRequired": true,
                                                    "locationRequired": true,
                                                    "enforceAccuracy": true,
                                                    "maxAccuracyM": 500,
                                                    "maxAgeSeconds": 120,
                                                    "clockSkewSeconds": 30,
                                                    "rejectMocked": false,
                                                    "configurationVersion": "location-v1-example"
                                                },
                                                "capturedAt": "2026-11-10T07:57:59+00:00",
                                                "receivedAt": "2026-11-10T08:00:00+00:00",
                                                "ageSeconds": 121,
                                                "reportedMocked": false,
                                                "flags": [],
                                                "withinGeofence": null
                                            }
                                        }
                                    },
                                    "location_inaccurate": {
                                        "value": {
                                            "message": "Location evidence does not satisfy the attendance policy.",
                                            "code": "location_inaccurate",
                                            "timing": {
                                                "action": "clock_in",
                                                "eligible": true,
                                                "blockedCode": null,
                                                "message": null,
                                                "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                "opensAt": "2026-11-10T07:00:00+00:00",
                                                "closesAt": "2026-11-10T17:00:00+00:00",
                                                "timezone": "Africa/Lagos",
                                                "policyVersion": "timing-v1-example",
                                                "shiftId": 9,
                                                "shiftRevision": 1,
                                                "recordedAt": "2026-11-10T08:00:00+00:00",
                                                "classification": "on_time",
                                                "minutesFromSchedule": 0,
                                                "appliedGraceMinutes": 10,
                                                "earlyGraceMinutes": 0,
                                                "lateGraceMinutes": 10,
                                                "reasonRequired": false,
                                                "reviewRequired": false
                                            },
                                            "location": {
                                                "projectId": 2,
                                                "expected": {
                                                    "latitude": 6.5,
                                                    "longitude": 3.4,
                                                    "radiusMeters": 100
                                                },
                                                "received": {
                                                    "latitude": 6.5,
                                                    "longitude": 3.4,
                                                    "accuracyMeters": 999
                                                },
                                                "distanceMeters": 0,
                                                "outsideByMeters": 0,
                                                "decision": "rejected",
                                                "locationStatus": "captured",
                                                "policy": {
                                                    "geofenceRequired": true,
                                                    "locationRequired": true,
                                                    "enforceAccuracy": true,
                                                    "maxAccuracyM": 500,
                                                    "maxAgeSeconds": 120,
                                                    "clockSkewSeconds": 30,
                                                    "rejectMocked": false,
                                                    "configurationVersion": "location-v1-example"
                                                },
                                                "capturedAt": "2026-11-10T08:00:00+00:00",
                                                "receivedAt": "2026-11-10T08:00:00+00:00",
                                                "ageSeconds": 0,
                                                "reportedMocked": false,
                                                "flags": [],
                                                "withinGeofence": null
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limited. Retry with backoff."
                    },
                    "409": {
                        "description": "Already clocked in, invalid break transition, changed shift/timing basis, or a punch request key reused with different details. clock_out_reconciliation_required means later break activity conflicts with the clock-out receipt: refresh current/history before a new attempt."
                    },
                    "200": {
                        "description": "Exact clock-in retry replayed.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "replayed": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": 42,
                                                "employeeId": 3,
                                                "state": "working",
                                                "status": "active",
                                                "clockIn": "2026-11-10T08:00:00+00:00",
                                                "clockOut": null,
                                                "totalHours": null,
                                                "verificationStatus": "verified",
                                                "verificationNote": null,
                                                "isGeofenceException": false,
                                                "exceptionReason": null,
                                                "rejectionReason": null,
                                                "shift": {
                                                    "id": 9,
                                                    "title": "Day shift",
                                                    "startTime": "2026-11-10T08:00:00+00:00",
                                                    "endTime": "2026-11-10T17:00:00+00:00"
                                                },
                                                "project": {
                                                    "id": 2,
                                                    "name": "Site",
                                                    "geofence": {
                                                        "projectId": 2,
                                                        "latitude": 6.5,
                                                        "longitude": 3.4,
                                                        "radiusMeters": 100
                                                    }
                                                },
                                                "breaks": [],
                                                "timing": {
                                                    "basis": {
                                                        "shiftId": 9,
                                                        "shiftRevision": 1,
                                                        "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                        "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                        "opensAt": "2026-11-10T07:00:00+00:00",
                                                        "closesAt": "2026-11-10T17:00:00+00:00",
                                                        "timezone": "Africa/Lagos",
                                                        "policyVersion": "timing-v1-example",
                                                        "source": "captured",
                                                        "rules": {
                                                            "early_clock_in_minutes": 60,
                                                            "early_arrival_grace_minutes": 0,
                                                            "late_grace_minutes": 10,
                                                            "early_grace_minutes": 15,
                                                            "clock_out_grace_minutes": 60,
                                                            "require_early_arrival_reason": false,
                                                            "require_late_arrival_reason": false,
                                                            "require_early_departure_reason": false,
                                                            "require_late_departure_reason": false
                                                        }
                                                    },
                                                    "clockIn": {
                                                        "action": "clock_in",
                                                        "eligible": true,
                                                        "blockedCode": null,
                                                        "message": null,
                                                        "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                        "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                        "opensAt": "2026-11-10T07:00:00+00:00",
                                                        "closesAt": "2026-11-10T17:00:00+00:00",
                                                        "timezone": "Africa/Lagos",
                                                        "policyVersion": "timing-v1-example",
                                                        "shiftId": 9,
                                                        "shiftRevision": 1,
                                                        "recordedAt": "2026-11-10T08:00:00+00:00",
                                                        "classification": "on_time",
                                                        "minutesFromSchedule": 0,
                                                        "appliedGraceMinutes": 10,
                                                        "earlyGraceMinutes": 0,
                                                        "lateGraceMinutes": 10,
                                                        "reasonRequired": false,
                                                        "reviewRequired": false,
                                                        "reason": null,
                                                        "reasonSatisfied": true,
                                                        "basisSource": "saved"
                                                    },
                                                    "clockOut": null
                                                },
                                                "clockInReceivedAt": "2026-11-10T08:00:00+00:00",
                                                "clockOutReceivedAt": null,
                                                "recordedElapsedHours": null,
                                                "locationDecisions": {
                                                    "clockIn": {
                                                        "projectId": 2,
                                                        "expected": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "radiusMeters": 100
                                                        },
                                                        "received": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "accuracyMeters": 10
                                                        },
                                                        "distanceMeters": 0,
                                                        "outsideByMeters": 0,
                                                        "decision": "verified",
                                                        "locationStatus": "captured",
                                                        "policy": {
                                                            "geofenceRequired": true,
                                                            "locationRequired": true,
                                                            "enforceAccuracy": true,
                                                            "maxAccuracyM": 500,
                                                            "maxAgeSeconds": 120,
                                                            "clockSkewSeconds": 30,
                                                            "rejectMocked": false,
                                                            "configurationVersion": "location-v1-example"
                                                        },
                                                        "capturedAt": "2026-11-10T08:00:00+00:00",
                                                        "receivedAt": "2026-11-10T08:00:00+00:00",
                                                        "ageSeconds": 0,
                                                        "reportedMocked": false,
                                                        "flags": [],
                                                        "withinGeofence": true
                                                    },
                                                    "clockOut": null
                                                },
                                                "location": {
                                                    "projectId": 2,
                                                    "expected": {
                                                        "latitude": 6.5,
                                                        "longitude": 3.4,
                                                        "radiusMeters": 100
                                                    },
                                                    "received": {
                                                        "latitude": 6.5,
                                                        "longitude": 3.4,
                                                        "accuracyMeters": 10
                                                    },
                                                    "distanceMeters": 0,
                                                    "outsideByMeters": 0,
                                                    "decision": "verified",
                                                    "locationStatus": "captured",
                                                    "policy": {
                                                        "geofenceRequired": true,
                                                        "locationRequired": true,
                                                        "enforceAccuracy": true,
                                                        "maxAccuracyM": 500,
                                                        "maxAgeSeconds": 120,
                                                        "clockSkewSeconds": 30,
                                                        "rejectMocked": false,
                                                        "configurationVersion": "location-v1-example"
                                                    },
                                                    "capturedAt": "2026-11-10T08:00:00+00:00",
                                                    "receivedAt": "2026-11-10T08:00:00+00:00",
                                                    "ageSeconds": 0,
                                                    "reportedMocked": false,
                                                    "flags": [],
                                                    "withinGeofence": true
                                                },
                                                "attendanceDecision": "accepted"
                                            },
                                            "replayed": true
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Location is optional without a fence unless require_location is explicitly enabled. Send locationStatus captured, permission_denied, services_disabled, timeout or unavailable. Captured evidence includes latitude, longitude, location_accuracy_m, locationCapturedAt with timezone offset and boolean locationIsMocked. Missing location omits coordinates. The server enforces accuracy, age and distance only when effective location policy requires them, and handles reported mock location according to policy. Optional shift_id overrides deterministic selection; shiftRevision rejects stale schedules. Identity and official time come from the server. Existing mode, PIN, device, captureId, assignment and leave rules apply. Response includes attendanceDecision, stored location/locationDecisions and authoritative timing. Reuse Idempotency-Key and identical payload for exact replay; changed retries return 409. Rejected location includes expected/received coordinates, policy, distance and outsideByMeters when measurable.",
                "parameters": [
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "minLength": 16,
                            "maxLength": 120,
                            "pattern": "^[A-Za-z0-9_-]{16,120}$"
                        },
                        "description": "Reuse the identical key and payload for one online punch attempt. Applies to clock-in and clock-out."
                    },
                    {
                        "name": "X-Attendance-Device",
                        "in": "header",
                        "required": false,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Required when clockInPolicy.requiresTrustedDevice is true; obtain approval using the existing attendance device registration flow."
                    }
                ],
                "x-generated": true
            }
        },
        "/api/v1/mobile/attendance/clock-out": {
            "post": {
                "summary": "Clock out using the open session project",
                "tags": [
                    "Attendance"
                ],
                "operationId": "mobileAttendanceClockOut",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "description": "Identity and official clock times are server derived. Location is optional unless locationPolicy.locationRequired is true. For locationStatus=captured, send latitude, longitude, location_accuracy_m, locationCapturedAt and locationIsMocked. Otherwise omit coordinates. The POST rechecks policy, schedule, security and location evidence.",
                                "properties": {
                                    "latitude": {
                                        "type": "number",
                                        "minimum": -90,
                                        "maximum": 90
                                    },
                                    "longitude": {
                                        "type": "number",
                                        "minimum": -180,
                                        "maximum": 180
                                    },
                                    "captureId": {
                                        "type": "string",
                                        "format": "uuid",
                                        "description": "Required for facial punches. Issue an action-bound capture and upload its photo first."
                                    },
                                    "location_accuracy_m": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 100000,
                                        "description": "Device-reported accuracy in metres. Enforced only by the effective locationPolicy."
                                    },
                                    "locationStatus": {
                                        "type": "string",
                                        "enum": [
                                            "captured",
                                            "permission_denied",
                                            "services_disabled",
                                            "timeout",
                                            "unavailable"
                                        ]
                                    },
                                    "locationCapturedAt": {
                                        "type": "string",
                                        "format": "date-time",
                                        "description": "Device evidence timestamp with offset; official attendance uses server receipt time."
                                    },
                                    "locationIsMocked": {
                                        "type": "boolean",
                                        "description": "Untrusted OS-reported mock-location flag."
                                    },
                                    "mode": {
                                        "type": "string",
                                        "enum": [
                                            "account",
                                            "employee_number",
                                            "facial"
                                        ]
                                    },
                                    "pin": {
                                        "type": "string",
                                        "description": "Required for employee-number punches when policy requires a PIN."
                                    },
                                    "attendanceId": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "description": "Current session ID. Send it to prevent a delayed request from closing a newer session."
                                    }
                                }
                            },
                            "example": {
                                "locationStatus": "captured",
                                "latitude": 6.5,
                                "longitude": 3.4,
                                "location_accuracy_m": 10,
                                "locationCapturedAt": "2026-11-10T08:00:00+00:00",
                                "locationIsMocked": false
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Your attendance data; all clock times are server generated and include timezone offsets.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": 42,
                                                "employeeId": 3,
                                                "state": "clocked_out",
                                                "status": "completed",
                                                "clockIn": "2026-11-10T08:00:00+00:00",
                                                "clockOut": "2026-11-10T16:00:00+00:00",
                                                "totalHours": 7.5,
                                                "verificationStatus": "verified",
                                                "verificationNote": null,
                                                "isGeofenceException": false,
                                                "exceptionReason": null,
                                                "rejectionReason": null,
                                                "shift": {
                                                    "id": 9,
                                                    "title": "Day shift",
                                                    "startTime": "2026-11-10T08:00:00+00:00",
                                                    "endTime": "2026-11-10T17:00:00+00:00"
                                                },
                                                "project": {
                                                    "id": 2,
                                                    "name": "Site",
                                                    "geofence": {
                                                        "projectId": 2,
                                                        "latitude": 6.5,
                                                        "longitude": 3.4,
                                                        "radiusMeters": 100
                                                    }
                                                },
                                                "breaks": [
                                                    {
                                                        "id": 7,
                                                        "kind": "lunch",
                                                        "startedAt": "2026-11-10T12:00:00+00:00",
                                                        "endedAt": "2026-11-10T12:30:00+00:00",
                                                        "paid": false,
                                                        "durationMinutes": 30
                                                    }
                                                ],
                                                "timing": {
                                                    "basis": {
                                                        "shiftId": 9,
                                                        "shiftRevision": 1,
                                                        "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                        "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                        "opensAt": "2026-11-10T07:00:00+00:00",
                                                        "closesAt": "2026-11-10T17:00:00+00:00",
                                                        "timezone": "Africa/Lagos",
                                                        "policyVersion": "timing-v1-example",
                                                        "source": "captured",
                                                        "rules": {
                                                            "early_clock_in_minutes": 60,
                                                            "early_arrival_grace_minutes": 0,
                                                            "late_grace_minutes": 10,
                                                            "early_grace_minutes": 15,
                                                            "clock_out_grace_minutes": 60,
                                                            "require_early_arrival_reason": false,
                                                            "require_late_arrival_reason": false,
                                                            "require_early_departure_reason": false,
                                                            "require_late_departure_reason": false
                                                        }
                                                    },
                                                    "clockIn": {
                                                        "action": "clock_in",
                                                        "eligible": true,
                                                        "blockedCode": null,
                                                        "message": null,
                                                        "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                        "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                        "opensAt": "2026-11-10T07:00:00+00:00",
                                                        "closesAt": "2026-11-10T17:00:00+00:00",
                                                        "timezone": "Africa/Lagos",
                                                        "policyVersion": "timing-v1-example",
                                                        "shiftId": 9,
                                                        "shiftRevision": 1,
                                                        "recordedAt": "2026-11-10T08:00:00+00:00",
                                                        "classification": "on_time",
                                                        "minutesFromSchedule": 0,
                                                        "appliedGraceMinutes": 10,
                                                        "earlyGraceMinutes": 0,
                                                        "lateGraceMinutes": 10,
                                                        "reasonRequired": false,
                                                        "reviewRequired": false,
                                                        "reason": null,
                                                        "reasonSatisfied": true,
                                                        "basisSource": "saved"
                                                    },
                                                    "clockOut": {
                                                        "action": "clock_out",
                                                        "eligible": true,
                                                        "blockedCode": null,
                                                        "message": null,
                                                        "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                        "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                        "opensAt": null,
                                                        "closesAt": null,
                                                        "timezone": "Africa/Lagos",
                                                        "policyVersion": "timing-v1-example",
                                                        "shiftId": 9,
                                                        "shiftRevision": 1,
                                                        "recordedAt": "2026-11-10T16:00:00+00:00",
                                                        "classification": "early",
                                                        "minutesFromSchedule": -60,
                                                        "appliedGraceMinutes": 15,
                                                        "earlyGraceMinutes": 15,
                                                        "lateGraceMinutes": 60,
                                                        "reasonRequired": false,
                                                        "reviewRequired": true,
                                                        "reason": null,
                                                        "reasonSatisfied": true,
                                                        "basisSource": "saved"
                                                    }
                                                },
                                                "clockInReceivedAt": "2026-11-10T08:00:00+00:00",
                                                "clockOutReceivedAt": "2026-11-10T16:00:00+00:00",
                                                "recordedElapsedHours": 8,
                                                "locationDecisions": {
                                                    "clockIn": {
                                                        "projectId": 2,
                                                        "expected": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "radiusMeters": 100
                                                        },
                                                        "received": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "accuracyMeters": 10
                                                        },
                                                        "distanceMeters": 0,
                                                        "outsideByMeters": 0,
                                                        "decision": "verified",
                                                        "locationStatus": "captured",
                                                        "policy": {
                                                            "geofenceRequired": true,
                                                            "locationRequired": true,
                                                            "enforceAccuracy": true,
                                                            "maxAccuracyM": 500,
                                                            "maxAgeSeconds": 120,
                                                            "clockSkewSeconds": 30,
                                                            "rejectMocked": false,
                                                            "configurationVersion": "location-v1-example"
                                                        },
                                                        "capturedAt": "2026-11-10T08:00:00+00:00",
                                                        "receivedAt": "2026-11-10T08:00:00+00:00",
                                                        "ageSeconds": 0,
                                                        "reportedMocked": false,
                                                        "flags": [],
                                                        "withinGeofence": true
                                                    },
                                                    "clockOut": {
                                                        "projectId": 2,
                                                        "expected": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "radiusMeters": 100
                                                        },
                                                        "received": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "accuracyMeters": 10
                                                        },
                                                        "distanceMeters": 0,
                                                        "outsideByMeters": 0,
                                                        "decision": "verified",
                                                        "locationStatus": "captured",
                                                        "policy": {
                                                            "geofenceRequired": true,
                                                            "locationRequired": true,
                                                            "enforceAccuracy": true,
                                                            "maxAccuracyM": 500,
                                                            "maxAgeSeconds": 120,
                                                            "clockSkewSeconds": 30,
                                                            "rejectMocked": false,
                                                            "configurationVersion": "location-v1-example"
                                                        },
                                                        "capturedAt": "2026-11-10T16:00:00+00:00",
                                                        "receivedAt": "2026-11-10T16:00:00+00:00",
                                                        "ageSeconds": 0,
                                                        "reportedMocked": false,
                                                        "flags": [],
                                                        "withinGeofence": true
                                                    }
                                                },
                                                "location": {
                                                    "projectId": 2,
                                                    "expected": {
                                                        "latitude": 6.5,
                                                        "longitude": 3.4,
                                                        "radiusMeters": 100
                                                    },
                                                    "received": {
                                                        "latitude": 6.5,
                                                        "longitude": 3.4,
                                                        "accuracyMeters": 10
                                                    },
                                                    "distanceMeters": 0,
                                                    "outsideByMeters": 0,
                                                    "decision": "verified",
                                                    "locationStatus": "captured",
                                                    "policy": {
                                                        "geofenceRequired": true,
                                                        "locationRequired": true,
                                                        "enforceAccuracy": true,
                                                        "maxAccuracyM": 500,
                                                        "maxAgeSeconds": 120,
                                                        "clockSkewSeconds": 30,
                                                        "rejectMocked": false,
                                                        "configurationVersion": "location-v1-example"
                                                    },
                                                    "capturedAt": "2026-11-10T16:00:00+00:00",
                                                    "receivedAt": "2026-11-10T16:00:00+00:00",
                                                    "ageSeconds": 0,
                                                    "reportedMocked": false,
                                                    "flags": [],
                                                    "withinGeofence": true
                                                },
                                                "attendanceDecision": "accepted"
                                            },
                                            "replayed": false
                                        }
                                    },
                                    "facialPending": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": 42,
                                                "employeeId": 3,
                                                "state": "clocked_out",
                                                "status": "pending_verification",
                                                "clockIn": "2026-11-10T08:00:00+00:00",
                                                "clockOut": "2026-11-10T16:00:00+00:00",
                                                "totalHours": 7.5,
                                                "verificationStatus": "pending",
                                                "verificationNote": null,
                                                "isGeofenceException": false,
                                                "exceptionReason": null,
                                                "rejectionReason": null,
                                                "shift": {
                                                    "id": 9,
                                                    "title": "Day shift",
                                                    "startTime": "2026-11-10T08:00:00+00:00",
                                                    "endTime": "2026-11-10T17:00:00+00:00"
                                                },
                                                "project": {
                                                    "id": 2,
                                                    "name": "Site",
                                                    "geofence": {
                                                        "projectId": 2,
                                                        "latitude": 6.5,
                                                        "longitude": 3.4,
                                                        "radiusMeters": 100
                                                    }
                                                },
                                                "breaks": [
                                                    {
                                                        "id": 7,
                                                        "kind": "lunch",
                                                        "startedAt": "2026-11-10T12:00:00+00:00",
                                                        "endedAt": "2026-11-10T12:30:00+00:00",
                                                        "paid": false,
                                                        "durationMinutes": 30
                                                    }
                                                ],
                                                "timing": {
                                                    "basis": {
                                                        "shiftId": 9,
                                                        "shiftRevision": 1,
                                                        "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                        "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                        "opensAt": "2026-11-10T07:00:00+00:00",
                                                        "closesAt": "2026-11-10T17:00:00+00:00",
                                                        "timezone": "Africa/Lagos",
                                                        "policyVersion": "timing-v1-example",
                                                        "source": "captured",
                                                        "rules": {
                                                            "early_clock_in_minutes": 60,
                                                            "early_arrival_grace_minutes": 0,
                                                            "late_grace_minutes": 10,
                                                            "early_grace_minutes": 15,
                                                            "clock_out_grace_minutes": 60,
                                                            "require_early_arrival_reason": false,
                                                            "require_late_arrival_reason": false,
                                                            "require_early_departure_reason": false,
                                                            "require_late_departure_reason": false
                                                        }
                                                    },
                                                    "clockIn": {
                                                        "action": "clock_in",
                                                        "eligible": true,
                                                        "blockedCode": null,
                                                        "message": null,
                                                        "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                        "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                        "opensAt": "2026-11-10T07:00:00+00:00",
                                                        "closesAt": "2026-11-10T17:00:00+00:00",
                                                        "timezone": "Africa/Lagos",
                                                        "policyVersion": "timing-v1-example",
                                                        "shiftId": 9,
                                                        "shiftRevision": 1,
                                                        "recordedAt": "2026-11-10T08:00:00+00:00",
                                                        "classification": "on_time",
                                                        "minutesFromSchedule": 0,
                                                        "appliedGraceMinutes": 10,
                                                        "earlyGraceMinutes": 0,
                                                        "lateGraceMinutes": 10,
                                                        "reasonRequired": false,
                                                        "reviewRequired": false,
                                                        "reason": null,
                                                        "reasonSatisfied": true,
                                                        "basisSource": "saved"
                                                    },
                                                    "clockOut": {
                                                        "action": "clock_out",
                                                        "eligible": true,
                                                        "blockedCode": null,
                                                        "message": null,
                                                        "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                        "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                        "opensAt": null,
                                                        "closesAt": null,
                                                        "timezone": "Africa/Lagos",
                                                        "policyVersion": "timing-v1-example",
                                                        "shiftId": 9,
                                                        "shiftRevision": 1,
                                                        "recordedAt": "2026-11-10T16:00:00+00:00",
                                                        "classification": "early",
                                                        "minutesFromSchedule": -60,
                                                        "appliedGraceMinutes": 15,
                                                        "earlyGraceMinutes": 15,
                                                        "lateGraceMinutes": 60,
                                                        "reasonRequired": false,
                                                        "reviewRequired": true,
                                                        "reason": null,
                                                        "reasonSatisfied": true,
                                                        "basisSource": "saved"
                                                    }
                                                },
                                                "clockInReceivedAt": "2026-11-10T08:00:00+00:00",
                                                "clockOutReceivedAt": "2026-11-10T16:00:00+00:00",
                                                "recordedElapsedHours": 8,
                                                "locationDecisions": {
                                                    "clockIn": {
                                                        "projectId": 2,
                                                        "expected": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "radiusMeters": 100
                                                        },
                                                        "received": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "accuracyMeters": 10
                                                        },
                                                        "distanceMeters": 0,
                                                        "outsideByMeters": 0,
                                                        "decision": "verified",
                                                        "locationStatus": "captured",
                                                        "policy": {
                                                            "geofenceRequired": true,
                                                            "locationRequired": true,
                                                            "enforceAccuracy": true,
                                                            "maxAccuracyM": 500,
                                                            "maxAgeSeconds": 120,
                                                            "clockSkewSeconds": 30,
                                                            "rejectMocked": false,
                                                            "configurationVersion": "location-v1-example"
                                                        },
                                                        "capturedAt": "2026-11-10T08:00:00+00:00",
                                                        "receivedAt": "2026-11-10T08:00:00+00:00",
                                                        "ageSeconds": 0,
                                                        "reportedMocked": false,
                                                        "flags": [],
                                                        "withinGeofence": true
                                                    },
                                                    "clockOut": {
                                                        "projectId": 2,
                                                        "expected": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "radiusMeters": 100
                                                        },
                                                        "received": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "accuracyMeters": 10
                                                        },
                                                        "distanceMeters": 0,
                                                        "outsideByMeters": 0,
                                                        "decision": "verified",
                                                        "locationStatus": "captured",
                                                        "policy": {
                                                            "geofenceRequired": true,
                                                            "locationRequired": true,
                                                            "enforceAccuracy": true,
                                                            "maxAccuracyM": 500,
                                                            "maxAgeSeconds": 120,
                                                            "clockSkewSeconds": 30,
                                                            "rejectMocked": false,
                                                            "configurationVersion": "location-v1-example"
                                                        },
                                                        "capturedAt": "2026-11-10T16:00:00+00:00",
                                                        "receivedAt": "2026-11-10T16:00:00+00:00",
                                                        "ageSeconds": 0,
                                                        "reportedMocked": false,
                                                        "flags": [],
                                                        "withinGeofence": true
                                                    }
                                                },
                                                "location": {
                                                    "projectId": 2,
                                                    "expected": {
                                                        "latitude": 6.5,
                                                        "longitude": 3.4,
                                                        "radiusMeters": 100
                                                    },
                                                    "received": {
                                                        "latitude": 6.5,
                                                        "longitude": 3.4,
                                                        "accuracyMeters": 10
                                                    },
                                                    "distanceMeters": 0,
                                                    "outsideByMeters": 0,
                                                    "decision": "verified",
                                                    "locationStatus": "captured",
                                                    "policy": {
                                                        "geofenceRequired": true,
                                                        "locationRequired": true,
                                                        "enforceAccuracy": true,
                                                        "maxAccuracyM": 500,
                                                        "maxAgeSeconds": 120,
                                                        "clockSkewSeconds": 30,
                                                        "rejectMocked": false,
                                                        "configurationVersion": "location-v1-example"
                                                    },
                                                    "capturedAt": "2026-11-10T16:00:00+00:00",
                                                    "receivedAt": "2026-11-10T16:00:00+00:00",
                                                    "ageSeconds": 0,
                                                    "reportedMocked": false,
                                                    "flags": [],
                                                    "withinGeofence": true
                                                },
                                                "attendanceDecision": "review_required"
                                            },
                                            "replayed": false
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired worker bearer token."
                    },
                    "403": {
                        "description": "Inactive worker, wrong tenant, blocked attendance module or incomplete password setup."
                    },
                    "404": {
                        "description": "Session is outside your employee scope, or no session is available for clock-out."
                    },
                    "422": {
                        "description": "Invalid attendance input or business rule. A configured project fence always requires inside coordinates.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "geofence": {
                                        "value": {
                                            "message": "Clocking requires a verified location inside this project geofence.",
                                            "code": "outside_geofence",
                                            "timing": {
                                                "action": "clock_out",
                                                "eligible": true,
                                                "blockedCode": null,
                                                "message": null,
                                                "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                "opensAt": null,
                                                "closesAt": null,
                                                "timezone": "Africa/Lagos",
                                                "policyVersion": "timing-v1-example",
                                                "shiftId": 9,
                                                "shiftRevision": 1,
                                                "recordedAt": "2026-11-10T16:00:00+00:00",
                                                "classification": "early",
                                                "minutesFromSchedule": -60,
                                                "appliedGraceMinutes": 15,
                                                "earlyGraceMinutes": 15,
                                                "lateGraceMinutes": 60,
                                                "reasonRequired": false,
                                                "reviewRequired": true
                                            },
                                            "location": {
                                                "projectId": 2,
                                                "expected": {
                                                    "latitude": 6.5,
                                                    "longitude": 3.4,
                                                    "radiusMeters": 100
                                                },
                                                "received": {
                                                    "latitude": 7,
                                                    "longitude": 3.4,
                                                    "accuracyMeters": 10
                                                },
                                                "distanceMeters": 55597.46,
                                                "outsideByMeters": 55497.46,
                                                "decision": "rejected",
                                                "locationStatus": "captured",
                                                "policy": {
                                                    "geofenceRequired": true,
                                                    "locationRequired": true,
                                                    "enforceAccuracy": true,
                                                    "maxAccuracyM": 500,
                                                    "maxAgeSeconds": 120,
                                                    "clockSkewSeconds": 30,
                                                    "rejectMocked": false,
                                                    "configurationVersion": "location-v1-example"
                                                },
                                                "capturedAt": "2026-11-10T16:00:00+00:00",
                                                "receivedAt": "2026-11-10T16:00:00+00:00",
                                                "ageSeconds": 0,
                                                "reportedMocked": false,
                                                "flags": [],
                                                "withinGeofence": false
                                            }
                                        }
                                    },
                                    "location_required": {
                                        "value": {
                                            "message": "Location evidence does not satisfy the attendance policy.",
                                            "code": "location_required",
                                            "timing": {
                                                "action": "clock_out",
                                                "eligible": true,
                                                "blockedCode": null,
                                                "message": null,
                                                "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                "opensAt": null,
                                                "closesAt": null,
                                                "timezone": "Africa/Lagos",
                                                "policyVersion": "timing-v1-example",
                                                "shiftId": 9,
                                                "shiftRevision": 1,
                                                "recordedAt": "2026-11-10T16:00:00+00:00",
                                                "classification": "early",
                                                "minutesFromSchedule": -60,
                                                "appliedGraceMinutes": 15,
                                                "earlyGraceMinutes": 15,
                                                "lateGraceMinutes": 60,
                                                "reasonRequired": false,
                                                "reviewRequired": true
                                            },
                                            "location": {
                                                "projectId": 2,
                                                "expected": {
                                                    "latitude": 6.5,
                                                    "longitude": 3.4,
                                                    "radiusMeters": 100
                                                },
                                                "received": {
                                                    "latitude": null,
                                                    "longitude": null,
                                                    "accuracyMeters": null
                                                },
                                                "distanceMeters": null,
                                                "outsideByMeters": null,
                                                "decision": "rejected",
                                                "locationStatus": null,
                                                "policy": {
                                                    "geofenceRequired": true,
                                                    "locationRequired": true,
                                                    "enforceAccuracy": true,
                                                    "maxAccuracyM": 500,
                                                    "maxAgeSeconds": 120,
                                                    "clockSkewSeconds": 30,
                                                    "rejectMocked": false,
                                                    "configurationVersion": "location-v1-example"
                                                },
                                                "capturedAt": null,
                                                "receivedAt": "2026-11-10T16:00:00+00:00",
                                                "ageSeconds": null,
                                                "reportedMocked": false,
                                                "flags": [],
                                                "withinGeofence": null
                                            }
                                        }
                                    },
                                    "location_permission_denied": {
                                        "value": {
                                            "message": "Location evidence does not satisfy the attendance policy.",
                                            "code": "location_permission_denied",
                                            "timing": {
                                                "action": "clock_out",
                                                "eligible": true,
                                                "blockedCode": null,
                                                "message": null,
                                                "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                "opensAt": null,
                                                "closesAt": null,
                                                "timezone": "Africa/Lagos",
                                                "policyVersion": "timing-v1-example",
                                                "shiftId": 9,
                                                "shiftRevision": 1,
                                                "recordedAt": "2026-11-10T16:00:00+00:00",
                                                "classification": "early",
                                                "minutesFromSchedule": -60,
                                                "appliedGraceMinutes": 15,
                                                "earlyGraceMinutes": 15,
                                                "lateGraceMinutes": 60,
                                                "reasonRequired": false,
                                                "reviewRequired": true
                                            },
                                            "location": {
                                                "projectId": 2,
                                                "expected": {
                                                    "latitude": 6.5,
                                                    "longitude": 3.4,
                                                    "radiusMeters": 100
                                                },
                                                "received": {
                                                    "latitude": null,
                                                    "longitude": null,
                                                    "accuracyMeters": null
                                                },
                                                "distanceMeters": null,
                                                "outsideByMeters": null,
                                                "decision": "rejected",
                                                "locationStatus": "permission_denied",
                                                "policy": {
                                                    "geofenceRequired": true,
                                                    "locationRequired": true,
                                                    "enforceAccuracy": true,
                                                    "maxAccuracyM": 500,
                                                    "maxAgeSeconds": 120,
                                                    "clockSkewSeconds": 30,
                                                    "rejectMocked": false,
                                                    "configurationVersion": "location-v1-example"
                                                },
                                                "capturedAt": null,
                                                "receivedAt": "2026-11-10T16:00:00+00:00",
                                                "ageSeconds": null,
                                                "reportedMocked": false,
                                                "flags": [],
                                                "withinGeofence": null
                                            }
                                        }
                                    },
                                    "location_services_disabled": {
                                        "value": {
                                            "message": "Location evidence does not satisfy the attendance policy.",
                                            "code": "location_services_disabled",
                                            "timing": {
                                                "action": "clock_out",
                                                "eligible": true,
                                                "blockedCode": null,
                                                "message": null,
                                                "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                "opensAt": null,
                                                "closesAt": null,
                                                "timezone": "Africa/Lagos",
                                                "policyVersion": "timing-v1-example",
                                                "shiftId": 9,
                                                "shiftRevision": 1,
                                                "recordedAt": "2026-11-10T16:00:00+00:00",
                                                "classification": "early",
                                                "minutesFromSchedule": -60,
                                                "appliedGraceMinutes": 15,
                                                "earlyGraceMinutes": 15,
                                                "lateGraceMinutes": 60,
                                                "reasonRequired": false,
                                                "reviewRequired": true
                                            },
                                            "location": {
                                                "projectId": 2,
                                                "expected": {
                                                    "latitude": 6.5,
                                                    "longitude": 3.4,
                                                    "radiusMeters": 100
                                                },
                                                "received": {
                                                    "latitude": null,
                                                    "longitude": null,
                                                    "accuracyMeters": null
                                                },
                                                "distanceMeters": null,
                                                "outsideByMeters": null,
                                                "decision": "rejected",
                                                "locationStatus": "services_disabled",
                                                "policy": {
                                                    "geofenceRequired": true,
                                                    "locationRequired": true,
                                                    "enforceAccuracy": true,
                                                    "maxAccuracyM": 500,
                                                    "maxAgeSeconds": 120,
                                                    "clockSkewSeconds": 30,
                                                    "rejectMocked": false,
                                                    "configurationVersion": "location-v1-example"
                                                },
                                                "capturedAt": null,
                                                "receivedAt": "2026-11-10T16:00:00+00:00",
                                                "ageSeconds": null,
                                                "reportedMocked": false,
                                                "flags": [],
                                                "withinGeofence": null
                                            }
                                        }
                                    },
                                    "location_timeout": {
                                        "value": {
                                            "message": "Location evidence does not satisfy the attendance policy.",
                                            "code": "location_timeout",
                                            "timing": {
                                                "action": "clock_out",
                                                "eligible": true,
                                                "blockedCode": null,
                                                "message": null,
                                                "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                "opensAt": null,
                                                "closesAt": null,
                                                "timezone": "Africa/Lagos",
                                                "policyVersion": "timing-v1-example",
                                                "shiftId": 9,
                                                "shiftRevision": 1,
                                                "recordedAt": "2026-11-10T16:00:00+00:00",
                                                "classification": "early",
                                                "minutesFromSchedule": -60,
                                                "appliedGraceMinutes": 15,
                                                "earlyGraceMinutes": 15,
                                                "lateGraceMinutes": 60,
                                                "reasonRequired": false,
                                                "reviewRequired": true
                                            },
                                            "location": {
                                                "projectId": 2,
                                                "expected": {
                                                    "latitude": 6.5,
                                                    "longitude": 3.4,
                                                    "radiusMeters": 100
                                                },
                                                "received": {
                                                    "latitude": null,
                                                    "longitude": null,
                                                    "accuracyMeters": null
                                                },
                                                "distanceMeters": null,
                                                "outsideByMeters": null,
                                                "decision": "rejected",
                                                "locationStatus": "timeout",
                                                "policy": {
                                                    "geofenceRequired": true,
                                                    "locationRequired": true,
                                                    "enforceAccuracy": true,
                                                    "maxAccuracyM": 500,
                                                    "maxAgeSeconds": 120,
                                                    "clockSkewSeconds": 30,
                                                    "rejectMocked": false,
                                                    "configurationVersion": "location-v1-example"
                                                },
                                                "capturedAt": null,
                                                "receivedAt": "2026-11-10T16:00:00+00:00",
                                                "ageSeconds": null,
                                                "reportedMocked": false,
                                                "flags": [],
                                                "withinGeofence": null
                                            }
                                        }
                                    },
                                    "location_unavailable": {
                                        "value": {
                                            "message": "Location evidence does not satisfy the attendance policy.",
                                            "code": "location_unavailable",
                                            "timing": {
                                                "action": "clock_out",
                                                "eligible": true,
                                                "blockedCode": null,
                                                "message": null,
                                                "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                "opensAt": null,
                                                "closesAt": null,
                                                "timezone": "Africa/Lagos",
                                                "policyVersion": "timing-v1-example",
                                                "shiftId": 9,
                                                "shiftRevision": 1,
                                                "recordedAt": "2026-11-10T16:00:00+00:00",
                                                "classification": "early",
                                                "minutesFromSchedule": -60,
                                                "appliedGraceMinutes": 15,
                                                "earlyGraceMinutes": 15,
                                                "lateGraceMinutes": 60,
                                                "reasonRequired": false,
                                                "reviewRequired": true
                                            },
                                            "location": {
                                                "projectId": 2,
                                                "expected": {
                                                    "latitude": 6.5,
                                                    "longitude": 3.4,
                                                    "radiusMeters": 100
                                                },
                                                "received": {
                                                    "latitude": null,
                                                    "longitude": null,
                                                    "accuracyMeters": null
                                                },
                                                "distanceMeters": null,
                                                "outsideByMeters": null,
                                                "decision": "rejected",
                                                "locationStatus": "unavailable",
                                                "policy": {
                                                    "geofenceRequired": true,
                                                    "locationRequired": true,
                                                    "enforceAccuracy": true,
                                                    "maxAccuracyM": 500,
                                                    "maxAgeSeconds": 120,
                                                    "clockSkewSeconds": 30,
                                                    "rejectMocked": false,
                                                    "configurationVersion": "location-v1-example"
                                                },
                                                "capturedAt": null,
                                                "receivedAt": "2026-11-10T16:00:00+00:00",
                                                "ageSeconds": null,
                                                "reportedMocked": false,
                                                "flags": [],
                                                "withinGeofence": null
                                            }
                                        }
                                    },
                                    "location_stale": {
                                        "value": {
                                            "message": "Location evidence does not satisfy the attendance policy.",
                                            "code": "location_stale",
                                            "timing": {
                                                "action": "clock_out",
                                                "eligible": true,
                                                "blockedCode": null,
                                                "message": null,
                                                "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                "opensAt": null,
                                                "closesAt": null,
                                                "timezone": "Africa/Lagos",
                                                "policyVersion": "timing-v1-example",
                                                "shiftId": 9,
                                                "shiftRevision": 1,
                                                "recordedAt": "2026-11-10T16:00:00+00:00",
                                                "classification": "early",
                                                "minutesFromSchedule": -60,
                                                "appliedGraceMinutes": 15,
                                                "earlyGraceMinutes": 15,
                                                "lateGraceMinutes": 60,
                                                "reasonRequired": false,
                                                "reviewRequired": true
                                            },
                                            "location": {
                                                "projectId": 2,
                                                "expected": {
                                                    "latitude": 6.5,
                                                    "longitude": 3.4,
                                                    "radiusMeters": 100
                                                },
                                                "received": {
                                                    "latitude": 6.5,
                                                    "longitude": 3.4,
                                                    "accuracyMeters": 10
                                                },
                                                "distanceMeters": 0,
                                                "outsideByMeters": 0,
                                                "decision": "rejected",
                                                "locationStatus": "captured",
                                                "policy": {
                                                    "geofenceRequired": true,
                                                    "locationRequired": true,
                                                    "enforceAccuracy": true,
                                                    "maxAccuracyM": 500,
                                                    "maxAgeSeconds": 120,
                                                    "clockSkewSeconds": 30,
                                                    "rejectMocked": false,
                                                    "configurationVersion": "location-v1-example"
                                                },
                                                "capturedAt": "2026-11-10T15:57:59+00:00",
                                                "receivedAt": "2026-11-10T16:00:00+00:00",
                                                "ageSeconds": 121,
                                                "reportedMocked": false,
                                                "flags": [],
                                                "withinGeofence": null
                                            }
                                        }
                                    },
                                    "location_inaccurate": {
                                        "value": {
                                            "message": "Location evidence does not satisfy the attendance policy.",
                                            "code": "location_inaccurate",
                                            "timing": {
                                                "action": "clock_out",
                                                "eligible": true,
                                                "blockedCode": null,
                                                "message": null,
                                                "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                "opensAt": null,
                                                "closesAt": null,
                                                "timezone": "Africa/Lagos",
                                                "policyVersion": "timing-v1-example",
                                                "shiftId": 9,
                                                "shiftRevision": 1,
                                                "recordedAt": "2026-11-10T16:00:00+00:00",
                                                "classification": "early",
                                                "minutesFromSchedule": -60,
                                                "appliedGraceMinutes": 15,
                                                "earlyGraceMinutes": 15,
                                                "lateGraceMinutes": 60,
                                                "reasonRequired": false,
                                                "reviewRequired": true
                                            },
                                            "location": {
                                                "projectId": 2,
                                                "expected": {
                                                    "latitude": 6.5,
                                                    "longitude": 3.4,
                                                    "radiusMeters": 100
                                                },
                                                "received": {
                                                    "latitude": 6.5,
                                                    "longitude": 3.4,
                                                    "accuracyMeters": 999
                                                },
                                                "distanceMeters": 0,
                                                "outsideByMeters": 0,
                                                "decision": "rejected",
                                                "locationStatus": "captured",
                                                "policy": {
                                                    "geofenceRequired": true,
                                                    "locationRequired": true,
                                                    "enforceAccuracy": true,
                                                    "maxAccuracyM": 500,
                                                    "maxAgeSeconds": 120,
                                                    "clockSkewSeconds": 30,
                                                    "rejectMocked": false,
                                                    "configurationVersion": "location-v1-example"
                                                },
                                                "capturedAt": "2026-11-10T16:00:00+00:00",
                                                "receivedAt": "2026-11-10T16:00:00+00:00",
                                                "ageSeconds": 0,
                                                "reportedMocked": false,
                                                "flags": [],
                                                "withinGeofence": null
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limited. Retry with backoff."
                    },
                    "409": {
                        "description": "Already clocked in, invalid break transition, changed shift/timing basis, or a punch request key reused with different details. clock_out_reconciliation_required means later break activity conflicts with the clock-out receipt: refresh current/history before a new attempt."
                    }
                },
                "description": "Send attendanceId and a stable Idempotency-Key for safe retries. Location follows the open attendance project policy even if assignments changed. Optional without a fence unless independently required. Send locationStatus and, when captured, latitude, longitude, location_accuracy_m, locationCapturedAt and locationIsMocked. Missing/stale/inaccurate/outside required evidence returns a stable 422 code with timing and location details. The server closes breaks, calculates recorded hours using server receipt time and rebuilds the timesheet. Existing method, PIN, trusted-device and fresh action-bound facial capture checks remain. Response includes attendanceDecision and the stored clock-out location decision. Exact retries return the original record and stored location decision; changed keyed payloads return 409. No open session returns 404 no_open_session.",
                "parameters": [
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "minLength": 16,
                            "maxLength": 120,
                            "pattern": "^[A-Za-z0-9_-]{16,120}$"
                        },
                        "description": "Reuse the identical key and payload for one online punch attempt. Applies to clock-in and clock-out."
                    },
                    {
                        "name": "X-Attendance-Device",
                        "in": "header",
                        "required": false,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Required when clockInPolicy.requiresTrustedDevice is true; obtain approval using the existing attendance device registration flow."
                    }
                ],
                "x-generated": true
            }
        },
        "/api/v1/mobile/attendance/current": {
            "get": {
                "summary": "View server-owned attendance context",
                "tags": [
                    "Attendance"
                ],
                "operationId": "mobileAttendanceCurrent",
                "parameters": [],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Your attendance data; all clock times are server generated and include timezone offsets.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "state": "working",
                                                "session": {
                                                    "id": 42,
                                                    "employeeId": 3,
                                                    "state": "working",
                                                    "status": "active",
                                                    "clockIn": "2026-11-10T08:00:00+00:00",
                                                    "clockOut": null,
                                                    "totalHours": null,
                                                    "verificationStatus": "verified",
                                                    "verificationNote": null,
                                                    "isGeofenceException": false,
                                                    "exceptionReason": null,
                                                    "rejectionReason": null,
                                                    "shift": {
                                                        "id": 9,
                                                        "title": "Day shift",
                                                        "startTime": "2026-11-10T08:00:00+00:00",
                                                        "endTime": "2026-11-10T17:00:00+00:00"
                                                    },
                                                    "project": {
                                                        "id": 2,
                                                        "name": "Site",
                                                        "geofence": {
                                                            "projectId": 2,
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "radiusMeters": 100
                                                        }
                                                    },
                                                    "breaks": [],
                                                    "timing": {
                                                        "basis": {
                                                            "shiftId": 9,
                                                            "shiftRevision": 1,
                                                            "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                            "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                            "opensAt": "2026-11-10T07:00:00+00:00",
                                                            "closesAt": "2026-11-10T17:00:00+00:00",
                                                            "timezone": "Africa/Lagos",
                                                            "policyVersion": "timing-v1-example",
                                                            "source": "captured",
                                                            "rules": {
                                                                "early_clock_in_minutes": 60,
                                                                "early_arrival_grace_minutes": 0,
                                                                "late_grace_minutes": 10,
                                                                "early_grace_minutes": 15,
                                                                "clock_out_grace_minutes": 60,
                                                                "require_early_arrival_reason": false,
                                                                "require_late_arrival_reason": false,
                                                                "require_early_departure_reason": false,
                                                                "require_late_departure_reason": false
                                                            }
                                                        },
                                                        "clockIn": {
                                                            "action": "clock_in",
                                                            "eligible": true,
                                                            "blockedCode": null,
                                                            "message": null,
                                                            "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                            "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                            "opensAt": "2026-11-10T07:00:00+00:00",
                                                            "closesAt": "2026-11-10T17:00:00+00:00",
                                                            "timezone": "Africa/Lagos",
                                                            "policyVersion": "timing-v1-example",
                                                            "shiftId": 9,
                                                            "shiftRevision": 1,
                                                            "recordedAt": "2026-11-10T08:00:00+00:00",
                                                            "classification": "on_time",
                                                            "minutesFromSchedule": 0,
                                                            "appliedGraceMinutes": 10,
                                                            "earlyGraceMinutes": 0,
                                                            "lateGraceMinutes": 10,
                                                            "reasonRequired": false,
                                                            "reviewRequired": false,
                                                            "reason": null,
                                                            "reasonSatisfied": true,
                                                            "basisSource": "saved"
                                                        },
                                                        "clockOut": null
                                                    },
                                                    "clockInReceivedAt": "2026-11-10T08:00:00+00:00",
                                                    "clockOutReceivedAt": null,
                                                    "recordedElapsedHours": null,
                                                    "locationDecisions": {
                                                        "clockIn": {
                                                            "projectId": 2,
                                                            "expected": {
                                                                "latitude": 6.5,
                                                                "longitude": 3.4,
                                                                "radiusMeters": 100
                                                            },
                                                            "received": {
                                                                "latitude": 6.5,
                                                                "longitude": 3.4,
                                                                "accuracyMeters": 10
                                                            },
                                                            "distanceMeters": 0,
                                                            "outsideByMeters": 0,
                                                            "decision": "verified",
                                                            "locationStatus": "captured",
                                                            "policy": {
                                                                "geofenceRequired": true,
                                                                "locationRequired": true,
                                                                "enforceAccuracy": true,
                                                                "maxAccuracyM": 500,
                                                                "maxAgeSeconds": 120,
                                                                "clockSkewSeconds": 30,
                                                                "rejectMocked": false,
                                                                "configurationVersion": "location-v1-example"
                                                            },
                                                            "capturedAt": "2026-11-10T08:00:00+00:00",
                                                            "receivedAt": "2026-11-10T08:00:00+00:00",
                                                            "ageSeconds": 0,
                                                            "reportedMocked": false,
                                                            "flags": [],
                                                            "withinGeofence": true
                                                        },
                                                        "clockOut": null
                                                    },
                                                    "location": {
                                                        "projectId": 2,
                                                        "expected": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "radiusMeters": 100
                                                        },
                                                        "received": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "accuracyMeters": 10
                                                        },
                                                        "distanceMeters": 0,
                                                        "outsideByMeters": 0,
                                                        "decision": "verified",
                                                        "locationStatus": "captured",
                                                        "policy": {
                                                            "geofenceRequired": true,
                                                            "locationRequired": true,
                                                            "enforceAccuracy": true,
                                                            "maxAccuracyM": 500,
                                                            "maxAgeSeconds": 120,
                                                            "clockSkewSeconds": 30,
                                                            "rejectMocked": false,
                                                            "configurationVersion": "location-v1-example"
                                                        },
                                                        "capturedAt": "2026-11-10T08:00:00+00:00",
                                                        "receivedAt": "2026-11-10T08:00:00+00:00",
                                                        "ageSeconds": 0,
                                                        "reportedMocked": false,
                                                        "flags": [],
                                                        "withinGeofence": true
                                                    },
                                                    "attendanceDecision": "accepted"
                                                },
                                                "serverTime": "2026-11-10T08:00:00+00:00",
                                                "selectedShiftId": 9,
                                                "geofence": {
                                                    "projectId": 2,
                                                    "latitude": 6.5,
                                                    "longitude": 3.4,
                                                    "radiusMeters": 100
                                                },
                                                "locationPolicy": {
                                                    "geofenceRequired": true,
                                                    "locationRequired": true,
                                                    "enforceAccuracy": true,
                                                    "maxAccuracyM": 500,
                                                    "maxAgeSeconds": 120,
                                                    "clockSkewSeconds": 30,
                                                    "rejectMocked": false,
                                                    "configurationVersion": "location-v1-example"
                                                },
                                                "clockInDecision": {
                                                    "action": "clock_in",
                                                    "eligible": false,
                                                    "blockedCode": "already_clocked_in",
                                                    "message": "You already have an open attendance session.",
                                                    "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                    "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                    "opensAt": "2026-11-10T07:00:00+00:00",
                                                    "closesAt": "2026-11-10T17:00:00+00:00",
                                                    "timezone": "Africa/Lagos",
                                                    "policyVersion": "timing-v1-example",
                                                    "shiftId": 9,
                                                    "shiftRevision": 1,
                                                    "recordedAt": "2026-11-10T08:00:00+00:00",
                                                    "classification": "on_time",
                                                    "minutesFromSchedule": 0,
                                                    "appliedGraceMinutes": 10,
                                                    "earlyGraceMinutes": 0,
                                                    "lateGraceMinutes": 10,
                                                    "reasonRequired": false,
                                                    "reviewRequired": false
                                                },
                                                "clockInPolicies": [
                                                    {
                                                        "shiftId": 9,
                                                        "projectId": 2,
                                                        "geofence": {
                                                            "projectId": 2,
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "radiusMeters": 100
                                                        },
                                                        "locationPolicy": {
                                                            "geofenceRequired": true,
                                                            "locationRequired": true,
                                                            "enforceAccuracy": true,
                                                            "maxAccuracyM": 500,
                                                            "maxAgeSeconds": 120,
                                                            "clockSkewSeconds": 30,
                                                            "rejectMocked": false,
                                                            "configurationVersion": "location-v1-example"
                                                        },
                                                        "policy": {
                                                            "method": "account",
                                                            "require_pin": false,
                                                            "require_trusted_device": false,
                                                            "supervisor_review": false,
                                                            "early_clock_in_minutes": 60,
                                                            "max_location_accuracy_m": 500,
                                                            "require_location": false,
                                                            "max_location_age_seconds": 120,
                                                            "location_clock_skew_seconds": 30,
                                                            "reject_mock_locations": false,
                                                            "early_arrival_grace_minutes": 0,
                                                            "late_grace_minutes": 10,
                                                            "early_grace_minutes": 15,
                                                            "clock_out_grace_minutes": 60,
                                                            "no_show_minutes": 60,
                                                            "require_early_arrival_reason": false,
                                                            "require_late_arrival_reason": false,
                                                            "require_early_departure_reason": false,
                                                            "require_late_departure_reason": false,
                                                            "modes": [
                                                                "account"
                                                            ],
                                                            "configuration_version": "example"
                                                        }
                                                    }
                                                ],
                                                "clockInEligibility": [
                                                    {
                                                        "action": "clock_in",
                                                        "eligible": false,
                                                        "blockedCode": "already_clocked_in",
                                                        "message": null,
                                                        "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                        "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                        "opensAt": "2026-11-10T07:00:00+00:00",
                                                        "closesAt": "2026-11-10T17:00:00+00:00",
                                                        "timezone": "Africa/Lagos",
                                                        "policyVersion": "timing-v1-example",
                                                        "shiftId": 9,
                                                        "shiftRevision": 1,
                                                        "recordedAt": "2026-11-10T08:00:00+00:00",
                                                        "classification": "on_time",
                                                        "minutesFromSchedule": 0,
                                                        "appliedGraceMinutes": 10,
                                                        "earlyGraceMinutes": 0,
                                                        "lateGraceMinutes": 10,
                                                        "reasonRequired": false,
                                                        "reviewRequired": false
                                                    }
                                                ],
                                                "clockOutEligibility": {
                                                    "action": "clock_out",
                                                    "eligible": true,
                                                    "blockedCode": null,
                                                    "message": null,
                                                    "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                    "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                    "opensAt": null,
                                                    "closesAt": null,
                                                    "timezone": "Africa/Lagos",
                                                    "policyVersion": "timing-v1-example",
                                                    "shiftId": 9,
                                                    "shiftRevision": 1,
                                                    "recordedAt": "2026-11-10T08:00:00+00:00",
                                                    "classification": "early",
                                                    "minutesFromSchedule": -540,
                                                    "appliedGraceMinutes": 15,
                                                    "earlyGraceMinutes": 15,
                                                    "lateGraceMinutes": 60,
                                                    "reasonRequired": false,
                                                    "reviewRequired": true
                                                },
                                                "breakPolicy": {
                                                    "name": "Site lunch",
                                                    "paid": false,
                                                    "requiredAfterHours": 6,
                                                    "minMinutes": 15,
                                                    "maxMinutes": 60
                                                },
                                                "clockInPolicy": {
                                                    "projectId": 2,
                                                    "locationPolicy": {
                                                        "geofenceRequired": true,
                                                        "locationRequired": true,
                                                        "enforceAccuracy": true,
                                                        "maxAccuracyM": 500,
                                                        "maxAgeSeconds": 120,
                                                        "clockSkewSeconds": 30,
                                                        "rejectMocked": false,
                                                        "configurationVersion": "location-v1-example"
                                                    },
                                                    "method": "account",
                                                    "facialReviewOnly": true,
                                                    "modes": [
                                                        "account"
                                                    ],
                                                    "requiresPin": false,
                                                    "requiresTrustedDevice": false,
                                                    "requiresSupervisorVerification": false,
                                                    "earlyClockInMinutes": 60,
                                                    "maxLocationAccuracyM": 500
                                                },
                                                "timezone": "Africa/Lagos"
                                            }
                                        }
                                    },
                                    "clockedOut": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "state": "clocked_out",
                                                "session": null,
                                                "serverTime": "2026-11-10T08:00:00+00:00",
                                                "selectedShiftId": 9,
                                                "geofence": {
                                                    "projectId": 2,
                                                    "latitude": 6.5,
                                                    "longitude": 3.4,
                                                    "radiusMeters": 100
                                                },
                                                "locationPolicy": {
                                                    "geofenceRequired": true,
                                                    "locationRequired": true,
                                                    "enforceAccuracy": true,
                                                    "maxAccuracyM": 500,
                                                    "maxAgeSeconds": 120,
                                                    "clockSkewSeconds": 30,
                                                    "rejectMocked": false,
                                                    "configurationVersion": "location-v1-example"
                                                },
                                                "clockInDecision": {
                                                    "action": "clock_in",
                                                    "eligible": true,
                                                    "blockedCode": null,
                                                    "message": null,
                                                    "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                    "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                    "opensAt": "2026-11-10T07:00:00+00:00",
                                                    "closesAt": "2026-11-10T17:00:00+00:00",
                                                    "timezone": "Africa/Lagos",
                                                    "policyVersion": "timing-v1-example",
                                                    "shiftId": 9,
                                                    "shiftRevision": 1,
                                                    "recordedAt": "2026-11-10T08:00:00+00:00",
                                                    "classification": "on_time",
                                                    "minutesFromSchedule": 0,
                                                    "appliedGraceMinutes": 10,
                                                    "earlyGraceMinutes": 0,
                                                    "lateGraceMinutes": 10,
                                                    "reasonRequired": false,
                                                    "reviewRequired": false
                                                },
                                                "clockInPolicies": [
                                                    {
                                                        "shiftId": 9,
                                                        "projectId": 2,
                                                        "geofence": {
                                                            "projectId": 2,
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "radiusMeters": 100
                                                        },
                                                        "locationPolicy": {
                                                            "geofenceRequired": true,
                                                            "locationRequired": true,
                                                            "enforceAccuracy": true,
                                                            "maxAccuracyM": 500,
                                                            "maxAgeSeconds": 120,
                                                            "clockSkewSeconds": 30,
                                                            "rejectMocked": false,
                                                            "configurationVersion": "location-v1-example"
                                                        },
                                                        "policy": {
                                                            "method": "account",
                                                            "require_pin": false,
                                                            "require_trusted_device": false,
                                                            "supervisor_review": false,
                                                            "early_clock_in_minutes": 60,
                                                            "max_location_accuracy_m": 500,
                                                            "require_location": false,
                                                            "max_location_age_seconds": 120,
                                                            "location_clock_skew_seconds": 30,
                                                            "reject_mock_locations": false,
                                                            "early_arrival_grace_minutes": 0,
                                                            "late_grace_minutes": 10,
                                                            "early_grace_minutes": 15,
                                                            "clock_out_grace_minutes": 60,
                                                            "no_show_minutes": 60,
                                                            "require_early_arrival_reason": false,
                                                            "require_late_arrival_reason": false,
                                                            "require_early_departure_reason": false,
                                                            "require_late_departure_reason": false,
                                                            "modes": [
                                                                "account"
                                                            ],
                                                            "configuration_version": "example"
                                                        }
                                                    }
                                                ],
                                                "clockInEligibility": [
                                                    {
                                                        "action": "clock_in",
                                                        "eligible": true,
                                                        "blockedCode": null,
                                                        "message": null,
                                                        "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                        "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                        "opensAt": "2026-11-10T07:00:00+00:00",
                                                        "closesAt": "2026-11-10T17:00:00+00:00",
                                                        "timezone": "Africa/Lagos",
                                                        "policyVersion": "timing-v1-example",
                                                        "shiftId": 9,
                                                        "shiftRevision": 1,
                                                        "recordedAt": "2026-11-10T08:00:00+00:00",
                                                        "classification": "on_time",
                                                        "minutesFromSchedule": 0,
                                                        "appliedGraceMinutes": 10,
                                                        "earlyGraceMinutes": 0,
                                                        "lateGraceMinutes": 10,
                                                        "reasonRequired": false,
                                                        "reviewRequired": false
                                                    }
                                                ],
                                                "clockOutEligibility": {
                                                    "action": "clock_out",
                                                    "shiftId": null,
                                                    "shiftRevision": null,
                                                    "eligible": false,
                                                    "blockedCode": "no_open_session",
                                                    "message": "There is no open attendance session to clock out of.",
                                                    "scheduledStart": null,
                                                    "scheduledEnd": null,
                                                    "opensAt": null,
                                                    "closesAt": null,
                                                    "timezone": "Africa/Lagos",
                                                    "classification": null,
                                                    "minutesFromSchedule": null,
                                                    "policyVersion": null,
                                                    "recordedAt": "2026-11-10T08:00:00+00:00",
                                                    "reasonRequired": false,
                                                    "reviewRequired": false
                                                },
                                                "breakPolicy": {
                                                    "name": "Site lunch",
                                                    "paid": false,
                                                    "requiredAfterHours": 6,
                                                    "minMinutes": 15,
                                                    "maxMinutes": 60
                                                },
                                                "clockInPolicy": {
                                                    "projectId": 2,
                                                    "locationPolicy": {
                                                        "geofenceRequired": true,
                                                        "locationRequired": true,
                                                        "enforceAccuracy": true,
                                                        "maxAccuracyM": 500,
                                                        "maxAgeSeconds": 120,
                                                        "clockSkewSeconds": 30,
                                                        "rejectMocked": false,
                                                        "configurationVersion": "location-v1-example"
                                                    },
                                                    "method": "account",
                                                    "facialReviewOnly": true,
                                                    "modes": [
                                                        "account"
                                                    ],
                                                    "requiresPin": false,
                                                    "requiresTrustedDevice": false,
                                                    "requiresSupervisorVerification": false,
                                                    "earlyClockInMinutes": 60,
                                                    "maxLocationAccuracyM": 500
                                                },
                                                "timezone": "Africa/Lagos"
                                            }
                                        }
                                    },
                                    "onBreak": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "state": "on_break",
                                                "session": {
                                                    "id": 42,
                                                    "employeeId": 3,
                                                    "state": "on_break",
                                                    "status": "active",
                                                    "clockIn": "2026-11-10T08:00:00+00:00",
                                                    "clockOut": null,
                                                    "totalHours": null,
                                                    "verificationStatus": "verified",
                                                    "verificationNote": null,
                                                    "isGeofenceException": false,
                                                    "exceptionReason": null,
                                                    "rejectionReason": null,
                                                    "shift": {
                                                        "id": 9,
                                                        "title": "Day shift",
                                                        "startTime": "2026-11-10T08:00:00+00:00",
                                                        "endTime": "2026-11-10T17:00:00+00:00"
                                                    },
                                                    "project": {
                                                        "id": 2,
                                                        "name": "Site",
                                                        "geofence": {
                                                            "projectId": 2,
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "radiusMeters": 100
                                                        }
                                                    },
                                                    "breaks": [
                                                        {
                                                            "id": 7,
                                                            "kind": "lunch",
                                                            "startedAt": "2026-11-10T12:00:00+00:00",
                                                            "endedAt": null,
                                                            "paid": false,
                                                            "durationMinutes": 0
                                                        }
                                                    ],
                                                    "timing": {
                                                        "basis": {
                                                            "shiftId": 9,
                                                            "shiftRevision": 1,
                                                            "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                            "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                            "opensAt": "2026-11-10T07:00:00+00:00",
                                                            "closesAt": "2026-11-10T17:00:00+00:00",
                                                            "timezone": "Africa/Lagos",
                                                            "policyVersion": "timing-v1-example",
                                                            "source": "captured",
                                                            "rules": {
                                                                "early_clock_in_minutes": 60,
                                                                "early_arrival_grace_minutes": 0,
                                                                "late_grace_minutes": 10,
                                                                "early_grace_minutes": 15,
                                                                "clock_out_grace_minutes": 60,
                                                                "require_early_arrival_reason": false,
                                                                "require_late_arrival_reason": false,
                                                                "require_early_departure_reason": false,
                                                                "require_late_departure_reason": false
                                                            }
                                                        },
                                                        "clockIn": {
                                                            "action": "clock_in",
                                                            "eligible": true,
                                                            "blockedCode": null,
                                                            "message": null,
                                                            "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                            "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                            "opensAt": "2026-11-10T07:00:00+00:00",
                                                            "closesAt": "2026-11-10T17:00:00+00:00",
                                                            "timezone": "Africa/Lagos",
                                                            "policyVersion": "timing-v1-example",
                                                            "shiftId": 9,
                                                            "shiftRevision": 1,
                                                            "recordedAt": "2026-11-10T08:00:00+00:00",
                                                            "classification": "on_time",
                                                            "minutesFromSchedule": 0,
                                                            "appliedGraceMinutes": 10,
                                                            "earlyGraceMinutes": 0,
                                                            "lateGraceMinutes": 10,
                                                            "reasonRequired": false,
                                                            "reviewRequired": false,
                                                            "reason": null,
                                                            "reasonSatisfied": true,
                                                            "basisSource": "saved"
                                                        },
                                                        "clockOut": null
                                                    },
                                                    "clockInReceivedAt": "2026-11-10T08:00:00+00:00",
                                                    "clockOutReceivedAt": null,
                                                    "recordedElapsedHours": null,
                                                    "locationDecisions": {
                                                        "clockIn": {
                                                            "projectId": 2,
                                                            "expected": {
                                                                "latitude": 6.5,
                                                                "longitude": 3.4,
                                                                "radiusMeters": 100
                                                            },
                                                            "received": {
                                                                "latitude": 6.5,
                                                                "longitude": 3.4,
                                                                "accuracyMeters": 10
                                                            },
                                                            "distanceMeters": 0,
                                                            "outsideByMeters": 0,
                                                            "decision": "verified",
                                                            "locationStatus": "captured",
                                                            "policy": {
                                                                "geofenceRequired": true,
                                                                "locationRequired": true,
                                                                "enforceAccuracy": true,
                                                                "maxAccuracyM": 500,
                                                                "maxAgeSeconds": 120,
                                                                "clockSkewSeconds": 30,
                                                                "rejectMocked": false,
                                                                "configurationVersion": "location-v1-example"
                                                            },
                                                            "capturedAt": "2026-11-10T08:00:00+00:00",
                                                            "receivedAt": "2026-11-10T08:00:00+00:00",
                                                            "ageSeconds": 0,
                                                            "reportedMocked": false,
                                                            "flags": [],
                                                            "withinGeofence": true
                                                        },
                                                        "clockOut": null
                                                    },
                                                    "location": {
                                                        "projectId": 2,
                                                        "expected": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "radiusMeters": 100
                                                        },
                                                        "received": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "accuracyMeters": 10
                                                        },
                                                        "distanceMeters": 0,
                                                        "outsideByMeters": 0,
                                                        "decision": "verified",
                                                        "locationStatus": "captured",
                                                        "policy": {
                                                            "geofenceRequired": true,
                                                            "locationRequired": true,
                                                            "enforceAccuracy": true,
                                                            "maxAccuracyM": 500,
                                                            "maxAgeSeconds": 120,
                                                            "clockSkewSeconds": 30,
                                                            "rejectMocked": false,
                                                            "configurationVersion": "location-v1-example"
                                                        },
                                                        "capturedAt": "2026-11-10T08:00:00+00:00",
                                                        "receivedAt": "2026-11-10T08:00:00+00:00",
                                                        "ageSeconds": 0,
                                                        "reportedMocked": false,
                                                        "flags": [],
                                                        "withinGeofence": true
                                                    },
                                                    "attendanceDecision": "accepted"
                                                },
                                                "serverTime": "2026-11-10T08:00:00+00:00",
                                                "selectedShiftId": 9,
                                                "geofence": {
                                                    "projectId": 2,
                                                    "latitude": 6.5,
                                                    "longitude": 3.4,
                                                    "radiusMeters": 100
                                                },
                                                "locationPolicy": {
                                                    "geofenceRequired": true,
                                                    "locationRequired": true,
                                                    "enforceAccuracy": true,
                                                    "maxAccuracyM": 500,
                                                    "maxAgeSeconds": 120,
                                                    "clockSkewSeconds": 30,
                                                    "rejectMocked": false,
                                                    "configurationVersion": "location-v1-example"
                                                },
                                                "clockInDecision": {
                                                    "action": "clock_in",
                                                    "eligible": false,
                                                    "blockedCode": "already_clocked_in",
                                                    "message": "You already have an open attendance session.",
                                                    "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                    "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                    "opensAt": "2026-11-10T07:00:00+00:00",
                                                    "closesAt": "2026-11-10T17:00:00+00:00",
                                                    "timezone": "Africa/Lagos",
                                                    "policyVersion": "timing-v1-example",
                                                    "shiftId": 9,
                                                    "shiftRevision": 1,
                                                    "recordedAt": "2026-11-10T08:00:00+00:00",
                                                    "classification": "on_time",
                                                    "minutesFromSchedule": 0,
                                                    "appliedGraceMinutes": 10,
                                                    "earlyGraceMinutes": 0,
                                                    "lateGraceMinutes": 10,
                                                    "reasonRequired": false,
                                                    "reviewRequired": false
                                                },
                                                "clockInPolicies": [
                                                    {
                                                        "shiftId": 9,
                                                        "projectId": 2,
                                                        "geofence": {
                                                            "projectId": 2,
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "radiusMeters": 100
                                                        },
                                                        "locationPolicy": {
                                                            "geofenceRequired": true,
                                                            "locationRequired": true,
                                                            "enforceAccuracy": true,
                                                            "maxAccuracyM": 500,
                                                            "maxAgeSeconds": 120,
                                                            "clockSkewSeconds": 30,
                                                            "rejectMocked": false,
                                                            "configurationVersion": "location-v1-example"
                                                        },
                                                        "policy": {
                                                            "method": "account",
                                                            "require_pin": false,
                                                            "require_trusted_device": false,
                                                            "supervisor_review": false,
                                                            "early_clock_in_minutes": 60,
                                                            "max_location_accuracy_m": 500,
                                                            "require_location": false,
                                                            "max_location_age_seconds": 120,
                                                            "location_clock_skew_seconds": 30,
                                                            "reject_mock_locations": false,
                                                            "early_arrival_grace_minutes": 0,
                                                            "late_grace_minutes": 10,
                                                            "early_grace_minutes": 15,
                                                            "clock_out_grace_minutes": 60,
                                                            "no_show_minutes": 60,
                                                            "require_early_arrival_reason": false,
                                                            "require_late_arrival_reason": false,
                                                            "require_early_departure_reason": false,
                                                            "require_late_departure_reason": false,
                                                            "modes": [
                                                                "account"
                                                            ],
                                                            "configuration_version": "example"
                                                        }
                                                    }
                                                ],
                                                "clockInEligibility": [
                                                    {
                                                        "action": "clock_in",
                                                        "eligible": false,
                                                        "blockedCode": "already_clocked_in",
                                                        "message": null,
                                                        "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                        "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                        "opensAt": "2026-11-10T07:00:00+00:00",
                                                        "closesAt": "2026-11-10T17:00:00+00:00",
                                                        "timezone": "Africa/Lagos",
                                                        "policyVersion": "timing-v1-example",
                                                        "shiftId": 9,
                                                        "shiftRevision": 1,
                                                        "recordedAt": "2026-11-10T08:00:00+00:00",
                                                        "classification": "on_time",
                                                        "minutesFromSchedule": 0,
                                                        "appliedGraceMinutes": 10,
                                                        "earlyGraceMinutes": 0,
                                                        "lateGraceMinutes": 10,
                                                        "reasonRequired": false,
                                                        "reviewRequired": false
                                                    }
                                                ],
                                                "clockOutEligibility": {
                                                    "action": "clock_out",
                                                    "eligible": true,
                                                    "blockedCode": null,
                                                    "message": null,
                                                    "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                    "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                    "opensAt": null,
                                                    "closesAt": null,
                                                    "timezone": "Africa/Lagos",
                                                    "policyVersion": "timing-v1-example",
                                                    "shiftId": 9,
                                                    "shiftRevision": 1,
                                                    "recordedAt": "2026-11-10T08:00:00+00:00",
                                                    "classification": "early",
                                                    "minutesFromSchedule": -540,
                                                    "appliedGraceMinutes": 15,
                                                    "earlyGraceMinutes": 15,
                                                    "lateGraceMinutes": 60,
                                                    "reasonRequired": false,
                                                    "reviewRequired": true
                                                },
                                                "breakPolicy": {
                                                    "name": "Site lunch",
                                                    "paid": false,
                                                    "requiredAfterHours": 6,
                                                    "minMinutes": 15,
                                                    "maxMinutes": 60
                                                },
                                                "clockInPolicy": {
                                                    "projectId": 2,
                                                    "locationPolicy": {
                                                        "geofenceRequired": true,
                                                        "locationRequired": true,
                                                        "enforceAccuracy": true,
                                                        "maxAccuracyM": 500,
                                                        "maxAgeSeconds": 120,
                                                        "clockSkewSeconds": 30,
                                                        "rejectMocked": false,
                                                        "configurationVersion": "location-v1-example"
                                                    },
                                                    "method": "account",
                                                    "facialReviewOnly": true,
                                                    "modes": [
                                                        "account"
                                                    ],
                                                    "requiresPin": false,
                                                    "requiresTrustedDevice": false,
                                                    "requiresSupervisorVerification": false,
                                                    "earlyClockInMinutes": 60,
                                                    "maxLocationAccuracyM": 500
                                                },
                                                "timezone": "Africa/Lagos"
                                            }
                                        }
                                    },
                                    "unfenced": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "state": "clocked_out",
                                                "session": null,
                                                "serverTime": "2026-11-10T08:00:00+00:00",
                                                "selectedShiftId": 9,
                                                "geofence": null,
                                                "locationPolicy": {
                                                    "geofenceRequired": false,
                                                    "locationRequired": false,
                                                    "enforceAccuracy": false,
                                                    "maxAccuracyM": null,
                                                    "maxAgeSeconds": null,
                                                    "clockSkewSeconds": 30,
                                                    "rejectMocked": false,
                                                    "configurationVersion": "location-v1-unfenced-example"
                                                },
                                                "clockInDecision": {
                                                    "action": "clock_in",
                                                    "eligible": true,
                                                    "blockedCode": null,
                                                    "message": null,
                                                    "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                    "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                    "opensAt": "2026-11-10T07:00:00+00:00",
                                                    "closesAt": "2026-11-10T17:00:00+00:00",
                                                    "timezone": "Africa/Lagos",
                                                    "policyVersion": "timing-v1-example",
                                                    "shiftId": 9,
                                                    "shiftRevision": 1,
                                                    "recordedAt": "2026-11-10T08:00:00+00:00",
                                                    "classification": "on_time",
                                                    "minutesFromSchedule": 0,
                                                    "appliedGraceMinutes": 10,
                                                    "earlyGraceMinutes": 0,
                                                    "lateGraceMinutes": 10,
                                                    "reasonRequired": false,
                                                    "reviewRequired": false
                                                },
                                                "clockInPolicies": [
                                                    {
                                                        "shiftId": 9,
                                                        "projectId": 2,
                                                        "geofence": null,
                                                        "locationPolicy": {
                                                            "geofenceRequired": false,
                                                            "locationRequired": false,
                                                            "enforceAccuracy": false,
                                                            "maxAccuracyM": null,
                                                            "maxAgeSeconds": null,
                                                            "clockSkewSeconds": 30,
                                                            "rejectMocked": false,
                                                            "configurationVersion": "location-v1-unfenced-example"
                                                        },
                                                        "policy": {
                                                            "method": "account",
                                                            "require_pin": false,
                                                            "require_trusted_device": false,
                                                            "supervisor_review": false,
                                                            "early_clock_in_minutes": 60,
                                                            "max_location_accuracy_m": 500,
                                                            "require_location": false,
                                                            "max_location_age_seconds": 120,
                                                            "location_clock_skew_seconds": 30,
                                                            "reject_mock_locations": false,
                                                            "early_arrival_grace_minutes": 0,
                                                            "late_grace_minutes": 10,
                                                            "early_grace_minutes": 15,
                                                            "clock_out_grace_minutes": 60,
                                                            "no_show_minutes": 60,
                                                            "require_early_arrival_reason": false,
                                                            "require_late_arrival_reason": false,
                                                            "require_early_departure_reason": false,
                                                            "require_late_departure_reason": false,
                                                            "modes": [
                                                                "account"
                                                            ],
                                                            "configuration_version": "example"
                                                        }
                                                    }
                                                ],
                                                "clockInEligibility": [
                                                    {
                                                        "action": "clock_in",
                                                        "eligible": true,
                                                        "blockedCode": null,
                                                        "message": null,
                                                        "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                        "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                        "opensAt": "2026-11-10T07:00:00+00:00",
                                                        "closesAt": "2026-11-10T17:00:00+00:00",
                                                        "timezone": "Africa/Lagos",
                                                        "policyVersion": "timing-v1-example",
                                                        "shiftId": 9,
                                                        "shiftRevision": 1,
                                                        "recordedAt": "2026-11-10T08:00:00+00:00",
                                                        "classification": "on_time",
                                                        "minutesFromSchedule": 0,
                                                        "appliedGraceMinutes": 10,
                                                        "earlyGraceMinutes": 0,
                                                        "lateGraceMinutes": 10,
                                                        "reasonRequired": false,
                                                        "reviewRequired": false
                                                    }
                                                ],
                                                "clockOutEligibility": {
                                                    "action": "clock_out",
                                                    "shiftId": null,
                                                    "shiftRevision": null,
                                                    "eligible": false,
                                                    "blockedCode": "no_open_session",
                                                    "message": "There is no open attendance session to clock out of.",
                                                    "scheduledStart": null,
                                                    "scheduledEnd": null,
                                                    "opensAt": null,
                                                    "closesAt": null,
                                                    "timezone": "Africa/Lagos",
                                                    "classification": null,
                                                    "minutesFromSchedule": null,
                                                    "policyVersion": null,
                                                    "recordedAt": "2026-11-10T08:00:00+00:00",
                                                    "reasonRequired": false,
                                                    "reviewRequired": false
                                                },
                                                "breakPolicy": {
                                                    "name": "Site lunch",
                                                    "paid": false,
                                                    "requiredAfterHours": 6,
                                                    "minMinutes": 15,
                                                    "maxMinutes": 60
                                                },
                                                "clockInPolicy": {
                                                    "projectId": 2,
                                                    "locationPolicy": {
                                                        "geofenceRequired": false,
                                                        "locationRequired": false,
                                                        "enforceAccuracy": false,
                                                        "maxAccuracyM": null,
                                                        "maxAgeSeconds": null,
                                                        "clockSkewSeconds": 30,
                                                        "rejectMocked": false,
                                                        "configurationVersion": "location-v1-unfenced-example"
                                                    },
                                                    "method": "account",
                                                    "facialReviewOnly": true,
                                                    "modes": [
                                                        "account"
                                                    ],
                                                    "requiresPin": false,
                                                    "requiresTrustedDevice": false,
                                                    "requiresSupervisorVerification": false,
                                                    "earlyClockInMinutes": 60,
                                                    "maxLocationAccuracyM": 500
                                                },
                                                "timezone": "Africa/Lagos"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired worker bearer token."
                    },
                    "403": {
                        "description": "Inactive worker, wrong tenant, blocked attendance module or incomplete password setup."
                    },
                    "404": {
                        "description": "Session is outside your employee scope, or no session is available for clock-out."
                    },
                    "422": {
                        "description": "Invalid input, supplied ownership fields, ineligible shift/location, disabled clock-in mode, failed PIN/device check, or lunch tracking does not apply."
                    },
                    "429": {
                        "description": "Rate limited. Retry with backoff."
                    }
                },
                "description": "Resolves your identity from the bearer token. Returns serverTime, selectedShiftId, clockInDecision, per-shift clockInEligibility, clockOutEligibility, geofence and explicit locationPolicy. Optional shift_id selects a published assigned shift; otherwise the latest ongoing shift wins, then the next shift today in company timezone. Tomorrow is never an automatic fallback. Open attendance pins clock-out policy to its recorded project. Future decisions are blocked until their window opens. No open session returns blockedCode no_open_session. locationPolicy declares geofenceRequired, locationRequired, enforceAccuracy, maxAccuracyM fixed at 500 metres when required (null when optional), nullable maxAgeSeconds, clockSkewSeconds, rejectMocked and configurationVersion. GET is advisory; POST rechecks all rules transactionally.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/attendance/history": {
            "get": {
                "summary": "List your attendance history",
                "tags": [
                    "Attendance"
                ],
                "operationId": "mobileAttendanceHistory",
                "parameters": [
                    {
                        "name": "startDate",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "endDate",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        }
                    },
                    {
                        "name": "perPage",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100,
                            "default": 20
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Your attendance data; all clock times are server generated and include timezone offsets.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": [
                                                {
                                                    "id": 42,
                                                    "employeeId": 3,
                                                    "state": "clocked_out",
                                                    "status": "completed",
                                                    "clockIn": "2026-11-10T08:00:00+00:00",
                                                    "clockOut": "2026-11-10T16:00:00+00:00",
                                                    "totalHours": 7.5,
                                                    "verificationStatus": "verified",
                                                    "verificationNote": null,
                                                    "isGeofenceException": false,
                                                    "exceptionReason": null,
                                                    "rejectionReason": null,
                                                    "shift": {
                                                        "id": 9,
                                                        "title": "Day shift",
                                                        "startTime": "2026-11-10T08:00:00+00:00",
                                                        "endTime": "2026-11-10T17:00:00+00:00"
                                                    },
                                                    "project": {
                                                        "id": 2,
                                                        "name": "Site",
                                                        "geofence": {
                                                            "projectId": 2,
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "radiusMeters": 100
                                                        }
                                                    },
                                                    "breaks": [
                                                        {
                                                            "id": 7,
                                                            "kind": "lunch",
                                                            "startedAt": "2026-11-10T12:00:00+00:00",
                                                            "endedAt": "2026-11-10T12:30:00+00:00",
                                                            "paid": false,
                                                            "durationMinutes": 30
                                                        }
                                                    ],
                                                    "timing": {
                                                        "basis": {
                                                            "shiftId": 9,
                                                            "shiftRevision": 1,
                                                            "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                            "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                            "opensAt": "2026-11-10T07:00:00+00:00",
                                                            "closesAt": "2026-11-10T17:00:00+00:00",
                                                            "timezone": "Africa/Lagos",
                                                            "policyVersion": "timing-v1-example",
                                                            "source": "captured",
                                                            "rules": {
                                                                "early_clock_in_minutes": 60,
                                                                "early_arrival_grace_minutes": 0,
                                                                "late_grace_minutes": 10,
                                                                "early_grace_minutes": 15,
                                                                "clock_out_grace_minutes": 60,
                                                                "require_early_arrival_reason": false,
                                                                "require_late_arrival_reason": false,
                                                                "require_early_departure_reason": false,
                                                                "require_late_departure_reason": false
                                                            }
                                                        },
                                                        "clockIn": {
                                                            "action": "clock_in",
                                                            "eligible": true,
                                                            "blockedCode": null,
                                                            "message": null,
                                                            "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                            "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                            "opensAt": "2026-11-10T07:00:00+00:00",
                                                            "closesAt": "2026-11-10T17:00:00+00:00",
                                                            "timezone": "Africa/Lagos",
                                                            "policyVersion": "timing-v1-example",
                                                            "shiftId": 9,
                                                            "shiftRevision": 1,
                                                            "recordedAt": "2026-11-10T08:00:00+00:00",
                                                            "classification": "on_time",
                                                            "minutesFromSchedule": 0,
                                                            "appliedGraceMinutes": 10,
                                                            "earlyGraceMinutes": 0,
                                                            "lateGraceMinutes": 10,
                                                            "reasonRequired": false,
                                                            "reviewRequired": false,
                                                            "reason": null,
                                                            "reasonSatisfied": true,
                                                            "basisSource": "saved"
                                                        },
                                                        "clockOut": {
                                                            "action": "clock_out",
                                                            "eligible": true,
                                                            "blockedCode": null,
                                                            "message": null,
                                                            "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                            "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                            "opensAt": null,
                                                            "closesAt": null,
                                                            "timezone": "Africa/Lagos",
                                                            "policyVersion": "timing-v1-example",
                                                            "shiftId": 9,
                                                            "shiftRevision": 1,
                                                            "recordedAt": "2026-11-10T16:00:00+00:00",
                                                            "classification": "early",
                                                            "minutesFromSchedule": -60,
                                                            "appliedGraceMinutes": 15,
                                                            "earlyGraceMinutes": 15,
                                                            "lateGraceMinutes": 60,
                                                            "reasonRequired": false,
                                                            "reviewRequired": true,
                                                            "reason": null,
                                                            "reasonSatisfied": true,
                                                            "basisSource": "saved"
                                                        }
                                                    },
                                                    "clockInReceivedAt": "2026-11-10T08:00:00+00:00",
                                                    "clockOutReceivedAt": "2026-11-10T16:00:00+00:00",
                                                    "recordedElapsedHours": 8,
                                                    "locationDecisions": {
                                                        "clockIn": {
                                                            "projectId": 2,
                                                            "expected": {
                                                                "latitude": 6.5,
                                                                "longitude": 3.4,
                                                                "radiusMeters": 100
                                                            },
                                                            "received": {
                                                                "latitude": 6.5,
                                                                "longitude": 3.4,
                                                                "accuracyMeters": 10
                                                            },
                                                            "distanceMeters": 0,
                                                            "outsideByMeters": 0,
                                                            "decision": "verified",
                                                            "locationStatus": "captured",
                                                            "policy": {
                                                                "geofenceRequired": true,
                                                                "locationRequired": true,
                                                                "enforceAccuracy": true,
                                                                "maxAccuracyM": 500,
                                                                "maxAgeSeconds": 120,
                                                                "clockSkewSeconds": 30,
                                                                "rejectMocked": false,
                                                                "configurationVersion": "location-v1-example"
                                                            },
                                                            "capturedAt": "2026-11-10T08:00:00+00:00",
                                                            "receivedAt": "2026-11-10T08:00:00+00:00",
                                                            "ageSeconds": 0,
                                                            "reportedMocked": false,
                                                            "flags": [],
                                                            "withinGeofence": true
                                                        },
                                                        "clockOut": {
                                                            "projectId": 2,
                                                            "expected": {
                                                                "latitude": 6.5,
                                                                "longitude": 3.4,
                                                                "radiusMeters": 100
                                                            },
                                                            "received": {
                                                                "latitude": 6.5,
                                                                "longitude": 3.4,
                                                                "accuracyMeters": 10
                                                            },
                                                            "distanceMeters": 0,
                                                            "outsideByMeters": 0,
                                                            "decision": "verified",
                                                            "locationStatus": "captured",
                                                            "policy": {
                                                                "geofenceRequired": true,
                                                                "locationRequired": true,
                                                                "enforceAccuracy": true,
                                                                "maxAccuracyM": 500,
                                                                "maxAgeSeconds": 120,
                                                                "clockSkewSeconds": 30,
                                                                "rejectMocked": false,
                                                                "configurationVersion": "location-v1-example"
                                                            },
                                                            "capturedAt": "2026-11-10T16:00:00+00:00",
                                                            "receivedAt": "2026-11-10T16:00:00+00:00",
                                                            "ageSeconds": 0,
                                                            "reportedMocked": false,
                                                            "flags": [],
                                                            "withinGeofence": true
                                                        }
                                                    },
                                                    "location": {
                                                        "projectId": 2,
                                                        "expected": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "radiusMeters": 100
                                                        },
                                                        "received": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "accuracyMeters": 10
                                                        },
                                                        "distanceMeters": 0,
                                                        "outsideByMeters": 0,
                                                        "decision": "verified",
                                                        "locationStatus": "captured",
                                                        "policy": {
                                                            "geofenceRequired": true,
                                                            "locationRequired": true,
                                                            "enforceAccuracy": true,
                                                            "maxAccuracyM": 500,
                                                            "maxAgeSeconds": 120,
                                                            "clockSkewSeconds": 30,
                                                            "rejectMocked": false,
                                                            "configurationVersion": "location-v1-example"
                                                        },
                                                        "capturedAt": "2026-11-10T16:00:00+00:00",
                                                        "receivedAt": "2026-11-10T16:00:00+00:00",
                                                        "ageSeconds": 0,
                                                        "reportedMocked": false,
                                                        "flags": [],
                                                        "withinGeofence": true
                                                    },
                                                    "attendanceDecision": "accepted"
                                                }
                                            ],
                                            "meta": {
                                                "current_page": 1,
                                                "last_page": 1,
                                                "per_page": 20,
                                                "total": 1,
                                                "timezone": "Africa/Lagos"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired worker bearer token."
                    },
                    "403": {
                        "description": "Inactive worker, wrong tenant, blocked attendance module or incomplete password setup."
                    },
                    "404": {
                        "description": "Session is outside your employee scope, or no session is available for clock-out."
                    },
                    "422": {
                        "description": "Invalid input, supplied ownership fields, ineligible shift/location, disabled clock-in mode, failed PIN/device check, or lunch tracking does not apply."
                    },
                    "429": {
                        "description": "Rate limited. Retry with backoff."
                    }
                },
                "description": "Returns only your attendance sessions, including active, completed, rejected and pending-verification records, newest clock-in first. Optional startDate and endDate (YYYY-MM-DD) filter the clock-in date in the organisation timezone, inclusive. Paginate with page and perPage (default 20, maximum 100).",
                "x-generated": true
            }
        },
        "/api/v1/mobile/attendance/history/{attendance}": {
            "get": {
                "summary": "View your attendance session",
                "tags": [
                    "Attendance"
                ],
                "operationId": "mobileAttendanceShow",
                "parameters": [
                    {
                        "name": "attendance",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "description": "Your attendance session id from history."
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Your attendance data; all clock times are server generated and include timezone offsets.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": 42,
                                                "employeeId": 3,
                                                "state": "clocked_out",
                                                "status": "completed",
                                                "clockIn": "2026-11-10T08:00:00+00:00",
                                                "clockOut": "2026-11-10T16:00:00+00:00",
                                                "totalHours": 7.5,
                                                "verificationStatus": "verified",
                                                "verificationNote": null,
                                                "isGeofenceException": false,
                                                "exceptionReason": null,
                                                "rejectionReason": null,
                                                "shift": {
                                                    "id": 9,
                                                    "title": "Day shift",
                                                    "startTime": "2026-11-10T08:00:00+00:00",
                                                    "endTime": "2026-11-10T17:00:00+00:00"
                                                },
                                                "project": {
                                                    "id": 2,
                                                    "name": "Site",
                                                    "geofence": {
                                                        "projectId": 2,
                                                        "latitude": 6.5,
                                                        "longitude": 3.4,
                                                        "radiusMeters": 100
                                                    }
                                                },
                                                "breaks": [
                                                    {
                                                        "id": 7,
                                                        "kind": "lunch",
                                                        "startedAt": "2026-11-10T12:00:00+00:00",
                                                        "endedAt": "2026-11-10T12:30:00+00:00",
                                                        "paid": false,
                                                        "durationMinutes": 30
                                                    }
                                                ],
                                                "timing": {
                                                    "basis": {
                                                        "shiftId": 9,
                                                        "shiftRevision": 1,
                                                        "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                        "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                        "opensAt": "2026-11-10T07:00:00+00:00",
                                                        "closesAt": "2026-11-10T17:00:00+00:00",
                                                        "timezone": "Africa/Lagos",
                                                        "policyVersion": "timing-v1-example",
                                                        "source": "captured",
                                                        "rules": {
                                                            "early_clock_in_minutes": 60,
                                                            "early_arrival_grace_minutes": 0,
                                                            "late_grace_minutes": 10,
                                                            "early_grace_minutes": 15,
                                                            "clock_out_grace_minutes": 60,
                                                            "require_early_arrival_reason": false,
                                                            "require_late_arrival_reason": false,
                                                            "require_early_departure_reason": false,
                                                            "require_late_departure_reason": false
                                                        }
                                                    },
                                                    "clockIn": {
                                                        "action": "clock_in",
                                                        "eligible": true,
                                                        "blockedCode": null,
                                                        "message": null,
                                                        "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                        "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                        "opensAt": "2026-11-10T07:00:00+00:00",
                                                        "closesAt": "2026-11-10T17:00:00+00:00",
                                                        "timezone": "Africa/Lagos",
                                                        "policyVersion": "timing-v1-example",
                                                        "shiftId": 9,
                                                        "shiftRevision": 1,
                                                        "recordedAt": "2026-11-10T08:00:00+00:00",
                                                        "classification": "on_time",
                                                        "minutesFromSchedule": 0,
                                                        "appliedGraceMinutes": 10,
                                                        "earlyGraceMinutes": 0,
                                                        "lateGraceMinutes": 10,
                                                        "reasonRequired": false,
                                                        "reviewRequired": false,
                                                        "reason": null,
                                                        "reasonSatisfied": true,
                                                        "basisSource": "saved"
                                                    },
                                                    "clockOut": {
                                                        "action": "clock_out",
                                                        "eligible": true,
                                                        "blockedCode": null,
                                                        "message": null,
                                                        "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                        "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                        "opensAt": null,
                                                        "closesAt": null,
                                                        "timezone": "Africa/Lagos",
                                                        "policyVersion": "timing-v1-example",
                                                        "shiftId": 9,
                                                        "shiftRevision": 1,
                                                        "recordedAt": "2026-11-10T16:00:00+00:00",
                                                        "classification": "early",
                                                        "minutesFromSchedule": -60,
                                                        "appliedGraceMinutes": 15,
                                                        "earlyGraceMinutes": 15,
                                                        "lateGraceMinutes": 60,
                                                        "reasonRequired": false,
                                                        "reviewRequired": true,
                                                        "reason": null,
                                                        "reasonSatisfied": true,
                                                        "basisSource": "saved"
                                                    }
                                                },
                                                "clockInReceivedAt": "2026-11-10T08:00:00+00:00",
                                                "clockOutReceivedAt": "2026-11-10T16:00:00+00:00",
                                                "recordedElapsedHours": 8,
                                                "locationDecisions": {
                                                    "clockIn": {
                                                        "projectId": 2,
                                                        "expected": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "radiusMeters": 100
                                                        },
                                                        "received": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "accuracyMeters": 10
                                                        },
                                                        "distanceMeters": 0,
                                                        "outsideByMeters": 0,
                                                        "decision": "verified",
                                                        "locationStatus": "captured",
                                                        "policy": {
                                                            "geofenceRequired": true,
                                                            "locationRequired": true,
                                                            "enforceAccuracy": true,
                                                            "maxAccuracyM": 500,
                                                            "maxAgeSeconds": 120,
                                                            "clockSkewSeconds": 30,
                                                            "rejectMocked": false,
                                                            "configurationVersion": "location-v1-example"
                                                        },
                                                        "capturedAt": "2026-11-10T08:00:00+00:00",
                                                        "receivedAt": "2026-11-10T08:00:00+00:00",
                                                        "ageSeconds": 0,
                                                        "reportedMocked": false,
                                                        "flags": [],
                                                        "withinGeofence": true
                                                    },
                                                    "clockOut": {
                                                        "projectId": 2,
                                                        "expected": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "radiusMeters": 100
                                                        },
                                                        "received": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "accuracyMeters": 10
                                                        },
                                                        "distanceMeters": 0,
                                                        "outsideByMeters": 0,
                                                        "decision": "verified",
                                                        "locationStatus": "captured",
                                                        "policy": {
                                                            "geofenceRequired": true,
                                                            "locationRequired": true,
                                                            "enforceAccuracy": true,
                                                            "maxAccuracyM": 500,
                                                            "maxAgeSeconds": 120,
                                                            "clockSkewSeconds": 30,
                                                            "rejectMocked": false,
                                                            "configurationVersion": "location-v1-example"
                                                        },
                                                        "capturedAt": "2026-11-10T16:00:00+00:00",
                                                        "receivedAt": "2026-11-10T16:00:00+00:00",
                                                        "ageSeconds": 0,
                                                        "reportedMocked": false,
                                                        "flags": [],
                                                        "withinGeofence": true
                                                    }
                                                },
                                                "location": {
                                                    "projectId": 2,
                                                    "expected": {
                                                        "latitude": 6.5,
                                                        "longitude": 3.4,
                                                        "radiusMeters": 100
                                                    },
                                                    "received": {
                                                        "latitude": 6.5,
                                                        "longitude": 3.4,
                                                        "accuracyMeters": 10
                                                    },
                                                    "distanceMeters": 0,
                                                    "outsideByMeters": 0,
                                                    "decision": "verified",
                                                    "locationStatus": "captured",
                                                    "policy": {
                                                        "geofenceRequired": true,
                                                        "locationRequired": true,
                                                        "enforceAccuracy": true,
                                                        "maxAccuracyM": 500,
                                                        "maxAgeSeconds": 120,
                                                        "clockSkewSeconds": 30,
                                                        "rejectMocked": false,
                                                        "configurationVersion": "location-v1-example"
                                                    },
                                                    "capturedAt": "2026-11-10T16:00:00+00:00",
                                                    "receivedAt": "2026-11-10T16:00:00+00:00",
                                                    "ageSeconds": 0,
                                                    "reportedMocked": false,
                                                    "flags": [],
                                                    "withinGeofence": true
                                                },
                                                "attendanceDecision": "accepted"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired worker bearer token."
                    },
                    "403": {
                        "description": "Inactive worker, wrong tenant, blocked attendance module or incomplete password setup."
                    },
                    "404": {
                        "description": "Session is outside your employee scope, or no session is available for clock-out."
                    },
                    "422": {
                        "description": "Invalid input, supplied ownership fields, ineligible shift/location, disabled clock-in mode, failed PIN/device check, or lunch tracking does not apply."
                    },
                    "429": {
                        "description": "Rate limited. Retry with backoff."
                    }
                },
                "description": "Use id from your attendance history. Returns clock times, recorded hours, shift, project, breaks and review status. Another employee’s or tenant’s session returns 404. No private employee or payroll model is returned.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/attendance/history/{attendance}/adjustments": {
            "post": {
                "summary": "Adjustment (Face Workflow)",
                "tags": [
                    "Attendance"
                ],
                "operationId": "faceWorkflowAdjustment",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "description": "Identity and official clock times are server derived. Location is optional unless locationPolicy.locationRequired is true. For locationStatus=captured, send latitude, longitude, location_accuracy_m, locationCapturedAt and locationIsMocked. Otherwise omit coordinates. The POST rechecks policy, schedule, security and location evidence.",
                                "properties": {
                                    "latitude": {
                                        "type": "number",
                                        "minimum": -90,
                                        "maximum": 90
                                    },
                                    "longitude": {
                                        "type": "number",
                                        "minimum": -180,
                                        "maximum": 180
                                    }
                                }
                            },
                            "example": {
                                "clockIn": "2026-11-17T08:00:00Z",
                                "clockOut": "2026-11-17T16:00:00Z",
                                "reason": "Request correction; original clock events remain unchanged."
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "attendance",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "description": "Your attendance session id from history."
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Server-owned biometric workflow state",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "00000000-0000-4000-8000-000000000001",
                                                "status": "pending",
                                                "reason": "Worker correction request"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Permission, consent withdrawal or disabled fallback policy."
                    },
                    "409": {
                        "description": "Expired session, conflicting evidence or stale review."
                    },
                    "422": {
                        "description": "Invalid movement report, consent or image list."
                    },
                    "429": {
                        "description": "Rate limited."
                    }
                },
                "x-generated": true,
                "description": " Contract version 2 is additive to v1. Server-issued sessions precede the movement check. Automatic enrollment and attendance acceptance are disabled. Processing captures are polled through the existing owned capture endpoint. Identical evidence retries preserve bytes/report; different evidence returns 409. No vectors or scores are returned to workers."
            }
        },
        "/api/v1/mobile/attendance/history/{attendance}/timeline": {
            "get": {
                "summary": "Timeline (Face Workflow)",
                "tags": [
                    "Attendance"
                ],
                "operationId": "faceWorkflowTimeline",
                "parameters": [
                    {
                        "name": "attendance",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "description": "Your attendance session id from history."
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Server-owned biometric workflow state",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": [
                                                {
                                                    "id": "00000000-0000-4000-8000-000000000001",
                                                    "action": "attendance.rejected",
                                                    "reason": "Reviewer explanation",
                                                    "at": "2026-11-17T16:10:00Z"
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Permission, consent withdrawal or disabled fallback policy."
                    },
                    "409": {
                        "description": "Expired session, conflicting evidence or stale review."
                    },
                    "422": {
                        "description": "Invalid movement report, consent or image list."
                    },
                    "429": {
                        "description": "Rate limited."
                    }
                },
                "x-generated": true,
                "description": " Contract version 2 is additive to v1. Server-issued sessions precede the movement check. Automatic enrollment and attendance acceptance are disabled. Processing captures are polled through the existing owned capture endpoint. Identical evidence retries preserve bytes/report; different evidence returns 409. No vectors or scores are returned to workers."
            }
        },
        "/api/v1/mobile/attendance/history/{attendance}/timing-reason": {
            "post": {
                "summary": "Explain your recorded attendance timing",
                "tags": [
                    "Attendance"
                ],
                "operationId": "mobileAttendanceTimingReason",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "action",
                                    "reason",
                                    "recordedAt",
                                    "policyVersion"
                                ],
                                "properties": {
                                    "action": {
                                        "type": "string",
                                        "enum": [
                                            "clock_in",
                                            "clock_out"
                                        ]
                                    },
                                    "reason": {
                                        "type": "string",
                                        "minLength": 1,
                                        "maxLength": 2000
                                    },
                                    "recordedAt": {
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "policyVersion": {
                                        "type": "string",
                                        "maxLength": 80
                                    }
                                }
                            },
                            "example": {
                                "action": "clock_in",
                                "reason": "Traffic delayed my arrival.",
                                "recordedAt": "2026-11-10T08:20:00+00:00",
                                "policyVersion": "timing-v1-example"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "attendance",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "description": "Your attendance session id from history."
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Your attendance data; all clock times are server generated and include timezone offsets.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": 42,
                                                "employeeId": 3,
                                                "state": "clocked_out",
                                                "status": "completed",
                                                "clockIn": "2026-11-10T08:20:00+00:00",
                                                "clockOut": "2026-11-10T16:00:00+00:00",
                                                "totalHours": 7.17,
                                                "verificationStatus": "verified",
                                                "verificationNote": null,
                                                "isGeofenceException": false,
                                                "exceptionReason": null,
                                                "rejectionReason": null,
                                                "shift": {
                                                    "id": 9,
                                                    "title": "Day shift",
                                                    "startTime": "2026-11-10T08:00:00+00:00",
                                                    "endTime": "2026-11-10T17:00:00+00:00"
                                                },
                                                "project": {
                                                    "id": 2,
                                                    "name": "Site",
                                                    "geofence": {
                                                        "projectId": 2,
                                                        "latitude": 6.5,
                                                        "longitude": 3.4,
                                                        "radiusMeters": 100
                                                    }
                                                },
                                                "breaks": [
                                                    {
                                                        "id": 7,
                                                        "kind": "lunch",
                                                        "startedAt": "2026-11-10T12:00:00+00:00",
                                                        "endedAt": "2026-11-10T12:30:00+00:00",
                                                        "paid": false,
                                                        "durationMinutes": 30
                                                    }
                                                ],
                                                "timing": {
                                                    "basis": {
                                                        "shiftId": 9,
                                                        "shiftRevision": 1,
                                                        "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                        "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                        "opensAt": "2026-11-10T07:00:00+00:00",
                                                        "closesAt": "2026-11-10T17:00:00+00:00",
                                                        "timezone": "Africa/Lagos",
                                                        "policyVersion": "timing-v1-example",
                                                        "source": "captured",
                                                        "rules": {
                                                            "early_clock_in_minutes": 60,
                                                            "early_arrival_grace_minutes": 0,
                                                            "late_grace_minutes": 10,
                                                            "early_grace_minutes": 15,
                                                            "clock_out_grace_minutes": 60,
                                                            "require_early_arrival_reason": false,
                                                            "require_late_arrival_reason": true,
                                                            "require_early_departure_reason": false,
                                                            "require_late_departure_reason": false
                                                        }
                                                    },
                                                    "clockIn": {
                                                        "action": "clock_in",
                                                        "eligible": true,
                                                        "blockedCode": null,
                                                        "message": null,
                                                        "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                        "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                        "opensAt": "2026-11-10T07:00:00+00:00",
                                                        "closesAt": "2026-11-10T17:00:00+00:00",
                                                        "timezone": "Africa/Lagos",
                                                        "policyVersion": "timing-v1-example",
                                                        "shiftId": 9,
                                                        "shiftRevision": 1,
                                                        "recordedAt": "2026-11-10T08:20:00+00:00",
                                                        "classification": "late",
                                                        "minutesFromSchedule": 20,
                                                        "appliedGraceMinutes": 10,
                                                        "earlyGraceMinutes": 0,
                                                        "lateGraceMinutes": 10,
                                                        "reasonRequired": true,
                                                        "reviewRequired": true,
                                                        "reason": {
                                                            "text": "Traffic delayed my arrival.",
                                                            "recordedAt": "2026-11-10T08:20:00+00:00",
                                                            "classification": "late",
                                                            "policyVersion": "timing-v1-example",
                                                            "actorUserId": 12,
                                                            "submittedAt": "2026-11-10T08:25:00+00:00"
                                                        },
                                                        "reasonSatisfied": true,
                                                        "basisSource": "saved"
                                                    },
                                                    "clockOut": {
                                                        "action": "clock_out",
                                                        "eligible": true,
                                                        "blockedCode": null,
                                                        "message": null,
                                                        "scheduledStart": "2026-11-10T08:00:00+00:00",
                                                        "scheduledEnd": "2026-11-10T17:00:00+00:00",
                                                        "opensAt": null,
                                                        "closesAt": null,
                                                        "timezone": "Africa/Lagos",
                                                        "policyVersion": "timing-v1-example",
                                                        "shiftId": 9,
                                                        "shiftRevision": 1,
                                                        "recordedAt": "2026-11-10T16:00:00+00:00",
                                                        "classification": "early",
                                                        "minutesFromSchedule": -60,
                                                        "appliedGraceMinutes": 15,
                                                        "earlyGraceMinutes": 15,
                                                        "lateGraceMinutes": 60,
                                                        "reasonRequired": false,
                                                        "reviewRequired": true,
                                                        "reason": null,
                                                        "reasonSatisfied": true,
                                                        "basisSource": "saved"
                                                    }
                                                },
                                                "clockInReceivedAt": "2026-11-10T08:20:00+00:00",
                                                "clockOutReceivedAt": "2026-11-10T16:00:00+00:00",
                                                "recordedElapsedHours": 7.6667,
                                                "locationDecisions": {
                                                    "clockIn": {
                                                        "projectId": 2,
                                                        "expected": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "radiusMeters": 100
                                                        },
                                                        "received": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "accuracyMeters": 10
                                                        },
                                                        "distanceMeters": 0,
                                                        "outsideByMeters": 0,
                                                        "decision": "verified",
                                                        "locationStatus": "captured",
                                                        "policy": {
                                                            "geofenceRequired": true,
                                                            "locationRequired": true,
                                                            "enforceAccuracy": true,
                                                            "maxAccuracyM": 500,
                                                            "maxAgeSeconds": 120,
                                                            "clockSkewSeconds": 30,
                                                            "rejectMocked": false,
                                                            "configurationVersion": "location-v1-example"
                                                        },
                                                        "capturedAt": "2026-11-10T08:20:00+00:00",
                                                        "receivedAt": "2026-11-10T08:20:00+00:00",
                                                        "ageSeconds": 0,
                                                        "reportedMocked": false,
                                                        "flags": [],
                                                        "withinGeofence": true
                                                    },
                                                    "clockOut": {
                                                        "projectId": 2,
                                                        "expected": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "radiusMeters": 100
                                                        },
                                                        "received": {
                                                            "latitude": 6.5,
                                                            "longitude": 3.4,
                                                            "accuracyMeters": 10
                                                        },
                                                        "distanceMeters": 0,
                                                        "outsideByMeters": 0,
                                                        "decision": "verified",
                                                        "locationStatus": "captured",
                                                        "policy": {
                                                            "geofenceRequired": true,
                                                            "locationRequired": true,
                                                            "enforceAccuracy": true,
                                                            "maxAccuracyM": 500,
                                                            "maxAgeSeconds": 120,
                                                            "clockSkewSeconds": 30,
                                                            "rejectMocked": false,
                                                            "configurationVersion": "location-v1-example"
                                                        },
                                                        "capturedAt": "2026-11-10T16:00:00+00:00",
                                                        "receivedAt": "2026-11-10T16:00:00+00:00",
                                                        "ageSeconds": 0,
                                                        "reportedMocked": false,
                                                        "flags": [],
                                                        "withinGeofence": true
                                                    }
                                                },
                                                "location": {
                                                    "projectId": 2,
                                                    "expected": {
                                                        "latitude": 6.5,
                                                        "longitude": 3.4,
                                                        "radiusMeters": 100
                                                    },
                                                    "received": {
                                                        "latitude": 6.5,
                                                        "longitude": 3.4,
                                                        "accuracyMeters": 10
                                                    },
                                                    "distanceMeters": 0,
                                                    "outsideByMeters": 0,
                                                    "decision": "verified",
                                                    "locationStatus": "captured",
                                                    "policy": {
                                                        "geofenceRequired": true,
                                                        "locationRequired": true,
                                                        "enforceAccuracy": true,
                                                        "maxAccuracyM": 500,
                                                        "maxAgeSeconds": 120,
                                                        "clockSkewSeconds": 30,
                                                        "rejectMocked": false,
                                                        "configurationVersion": "location-v1-example"
                                                    },
                                                    "capturedAt": "2026-11-10T16:00:00+00:00",
                                                    "receivedAt": "2026-11-10T16:00:00+00:00",
                                                    "ageSeconds": 0,
                                                    "reportedMocked": false,
                                                    "flags": [],
                                                    "withinGeofence": true
                                                },
                                                "attendanceDecision": "accepted"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired worker bearer token."
                    },
                    "403": {
                        "description": "Inactive worker, wrong tenant, blocked attendance module or incomplete password setup."
                    },
                    "404": {
                        "description": "Session is outside your employee scope, or no session is available for clock-out."
                    },
                    "422": {
                        "description": "Invalid input, supplied ownership fields, ineligible shift/location, disabled clock-in mode, failed PIN/device check, or lunch tracking does not apply."
                    },
                    "429": {
                        "description": "Rate limited. Retry with backoff."
                    },
                    "409": {
                        "description": "Already clocked in, invalid break transition, changed shift/timing basis, or a punch request key reused with different details. clock_out_reconciliation_required means later break activity conflicts with the clock-out receipt: refresh current/history before a new attempt."
                    }
                },
                "description": "Send action=clock_in or clock_out, a non-empty reason up to 2000 characters, and recordedAt/policyVersion from that punch timing response. The session must belong to the authenticated employee. A changed classification basis returns 409 timing_basis_changed. Exact retries preserve the original reason entry and notification. Records an audited message for managers without changing recorded times, attendance approval or pay.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/auth/firebase-installation": {
            "put": {
                "summary": "Register this device for push notifications",
                "tags": [
                    "Notifications"
                ],
                "operationId": "mobileFirebaseInstallationUpdate",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "app_version": {
                                        "type": "string",
                                        "nullable": true,
                                        "description": "max: 40"
                                    },
                                    "device_name": {
                                        "type": "string",
                                        "nullable": true,
                                        "description": "max: 255"
                                    },
                                    "fid": {
                                        "type": "string",
                                        "description": "min: 20; max: 255"
                                    },
                                    "platform": {
                                        "type": "string",
                                        "enum": [
                                            "ios",
                                            "android"
                                        ]
                                    },
                                    "previous_fid": {
                                        "type": "string",
                                        "nullable": true,
                                        "description": "min: 20; max: 255"
                                    }
                                },
                                "required": [
                                    "fid",
                                    "platform"
                                ]
                            },
                            "example": {
                                "fid": "FIREBASE_INSTALLATION_ID",
                                "platform": "android",
                                "device_name": "Worker phone",
                                "app_version": "1.0.0"
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Send the fid supplied by Flutter Firebase registration. Send previous_fid when it changes. Associates the installation with your authenticated worker account and tenant.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "registered": {
                                        "value": {
                                            "status": "registered"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid credentials or expired bearer token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    },
                                    "setupRequired": {
                                        "value": {
                                            "status": "error",
                                            "code": "password_change_required",
                                            "message": "Replace your temporary password to continue."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "fid": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "Registration conflict/device limit, or idempotency key reused with different leave details.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "conflict": {
                                        "value": {
                                            "status": "conflict"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Send the fid supplied by Flutter Firebase registration. Send previous_fid when it changes. Associates the installation with your authenticated worker account and tenant.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/auth/forgot-password": {
            "post": {
                "summary": "Request a password recovery code",
                "tags": [
                    "Passwords"
                ],
                "operationId": "mobilePasswordRecoveryForgot",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "login": {
                                        "type": "string",
                                        "description": "max: 255"
                                    }
                                },
                                "required": [
                                    "login"
                                ]
                            },
                            "example": {
                                "login": "worker.notifications"
                            }
                        }
                    }
                },
                "security": [],
                "responses": {
                    "200": {
                        "description": "Send login with your username. Returns a challenge; eligible accounts receive a code by email. The response does not disclose whether the account exists.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "challengeIssued": {
                                        "value": {
                                            "status": "success",
                                            "challenge": "OPAQUE_CHALLENGE",
                                            "expiresIn": 600,
                                            "resendIn": 60,
                                            "message": "If this account has an eligible email address, a code is on its way."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "login": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Code delivery or streaming is unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "unavailable": {
                                        "value": {
                                            "status": "error",
                                            "message": "The service is temporarily unavailable."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Send login with your username. Returns a challenge; eligible accounts receive a code by email. The response does not disclose whether the account exists.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/auth/forgot-password/resend": {
            "post": {
                "summary": "Resend a password recovery code",
                "tags": [
                    "Passwords"
                ],
                "operationId": "mobilePasswordRecoveryResend",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "challenge": {
                                        "type": "string",
                                        "description": "max: 255"
                                    }
                                },
                                "required": [
                                    "challenge"
                                ]
                            },
                            "example": {
                                "challenge": "CHALLENGE_FROM_PREVIOUS_RESPONSE"
                            }
                        }
                    }
                },
                "security": [],
                "responses": {
                    "200": {
                        "description": "Send the recovery challenge to request another emailed code after the resend cooldown.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "resent": {
                                        "value": {
                                            "status": "success",
                                            "expiresIn": 600,
                                            "resendIn": 60
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "challenge": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    },
                                    "cooldown": {
                                        "value": {
                                            "status": "error",
                                            "code": "otp_cooldown",
                                            "resendIn": 45
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Send the recovery challenge to request another emailed code after the resend cooldown.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/auth/forgot-password/verify": {
            "post": {
                "summary": "Verify a password recovery code",
                "tags": [
                    "Passwords"
                ],
                "operationId": "mobilePasswordRecoveryVerify",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "challenge": {
                                        "type": "string",
                                        "description": "max: 255"
                                    },
                                    "code": {
                                        "type": "integer"
                                    }
                                },
                                "required": [
                                    "challenge",
                                    "code"
                                ]
                            },
                            "example": {
                                "challenge": "CHALLENGE_FROM_PREVIOUS_RESPONSE",
                                "code": "123456"
                            }
                        }
                    }
                },
                "security": [],
                "responses": {
                    "200": {
                        "description": "Send the recovery challenge and emailed code. Returns a single-use resetToken for POST /mobile/auth/reset-password.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "verified": {
                                        "value": {
                                            "status": "success",
                                            "resetToken": "SINGLE_USE_RESET_TOKEN",
                                            "expiresIn": 900
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "challenge": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    },
                                    "invalidCode": {
                                        "value": {
                                            "status": "error",
                                            "code": "otp_invalid",
                                            "message": "That code is incorrect. 4 attempts left."
                                        }
                                    },
                                    "expiredCode": {
                                        "value": {
                                            "status": "error",
                                            "code": "otp_expired",
                                            "message": "This code has expired. Sign in again."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Send the recovery challenge and emailed code. Returns a single-use resetToken for POST /mobile/auth/reset-password.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/auth/login": {
            "post": {
                "summary": "Sign in with username and password",
                "tags": [
                    "Login"
                ],
                "operationId": "mobileLoginInvoke",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "device_name": {
                                        "type": "string",
                                        "nullable": true,
                                        "description": "max: 255"
                                    },
                                    "login": {
                                        "type": "string",
                                        "description": "max: 255"
                                    },
                                    "password": {
                                        "type": "string"
                                    }
                                },
                                "required": [
                                    "login",
                                    "password"
                                ]
                            },
                            "example": {
                                "login": "worker.notifications",
                                "password": "YOUR_PASSWORD",
                                "device_name": "Worker phone"
                            }
                        }
                    }
                },
                "security": [],
                "responses": {
                    "200": {
                        "description": "Send login with your username, password and optional device_name. A permanent password returns a bearer token and queues an in-app login notification for your account. A temporary password returns an OTP challenge; its login notification is queued only after permanent password setup. Refreshing a token does not create another login notification.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "normalLogin": {
                                        "value": {
                                            "status": "success",
                                            "message": "Authentication successful.",
                                            "access_token": "FULL_ACCESS_TOKEN",
                                            "token_type": "Bearer",
                                            "onboarding": {
                                                "enforced": false,
                                                "enforcement": "none",
                                                "managedBy": "tenant_admin",
                                                "requiresSetup": false,
                                                "setupComplete": false,
                                                "profileIncomplete": true,
                                                "nextStep": "phone",
                                                "canUploadIdentityImage": true,
                                                "canSubmit": true,
                                                "status": "incomplete",
                                                "submittedAt": null
                                            },
                                            "user": {
                                                "id": 12,
                                                "name": "Ada Worker",
                                                "email": "worker@example.test",
                                                "username": "worker.notifications",
                                                "phone": null,
                                                "avatar": null,
                                                "status": "active",
                                                "two_factor_enabled": false,
                                                "must_change_password": false,
                                                "last_login_at": "2027-07-01T09:00:00+00:00",
                                                "created_at": "2027-07-01T08:00:00+00:00",
                                                "updated_at": "2027-07-01T09:00:00+00:00",
                                                "tenant_memberships": [
                                                    {
                                                        "id": 7,
                                                        "status": "active",
                                                        "tenant": {
                                                            "id": 1,
                                                            "uuid": "c14db530-179d-48c7-94f4-ea58b66e4201",
                                                            "name": "Demo Tenant",
                                                            "slug": "demo",
                                                            "code": "DEMO",
                                                            "status": "active",
                                                            "plan": null,
                                                            "currency": "NGN",
                                                            "country": "NG",
                                                            "timezone": "Africa/Lagos",
                                                            "logo_url": null,
                                                            "flag": "🇳🇬"
                                                        },
                                                        "role": {
                                                            "id": 6,
                                                            "name": "Crew Member",
                                                            "slug": "field-worker",
                                                            "scope": "tenant"
                                                        }
                                                    }
                                                ]
                                            }
                                        }
                                    },
                                    "firstLogin": {
                                        "value": {
                                            "status": "otp_required",
                                            "challenge": "OPAQUE_CHALLENGE",
                                            "message": "We sent a sign-in code to your email.",
                                            "expires_in": 600,
                                            "resend_in": 60
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid credentials or expired bearer token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "login": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Code delivery or streaming is unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "unavailable": {
                                        "value": {
                                            "status": "error",
                                            "message": "The service is temporarily unavailable."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Send login with your username, password and optional device_name. A permanent password returns a bearer token and queues an in-app login notification for your account. A temporary password returns an OTP challenge; its login notification is queued only after permanent password setup. Refreshing a token does not create another login notification.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/auth/login/resend-otp": {
            "post": {
                "summary": "Resend the first-login code",
                "tags": [
                    "Login"
                ],
                "operationId": "mobileLoginOtpResend",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "challenge": {
                                        "type": "string",
                                        "description": "max: 255"
                                    }
                                },
                                "required": [
                                    "challenge"
                                ]
                            },
                            "example": {
                                "challenge": "CHALLENGE_FROM_PREVIOUS_RESPONSE"
                            }
                        }
                    }
                },
                "security": [],
                "responses": {
                    "200": {
                        "description": "Send the login challenge to request another code by email. Wait for the resend cooldown before retrying.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "resent": {
                                        "value": {
                                            "status": "success",
                                            "expires_in": 600,
                                            "resend_in": 60
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "challenge": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    },
                                    "cooldown": {
                                        "value": {
                                            "status": "error",
                                            "code": "otp_cooldown",
                                            "resend_in": 45
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Send the login challenge to request another code by email. Wait for the resend cooldown before retrying.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/auth/login/verify-otp": {
            "post": {
                "summary": "Verify the first-login code",
                "tags": [
                    "Login"
                ],
                "operationId": "mobileLoginOtpVerify",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "challenge": {
                                        "type": "string",
                                        "description": "max: 255"
                                    },
                                    "code": {
                                        "type": "integer"
                                    }
                                },
                                "required": [
                                    "challenge",
                                    "code"
                                ]
                            },
                            "example": {
                                "challenge": "CHALLENGE_FROM_PREVIOUS_RESPONSE",
                                "code": "123456"
                            }
                        }
                    }
                },
                "security": [],
                "responses": {
                    "200": {
                        "description": "Send challenge and the six-digit code emailed after temporary-password login. Returns a 15-minute token for setting your permanent password. Use it with PUT /mobile/auth/password.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "verifiedFirstLogin": {
                                        "value": {
                                            "status": "success",
                                            "message": "Authentication successful.",
                                            "access_token": "RESTRICTED_ONBOARDING_TOKEN",
                                            "token_type": "Bearer",
                                            "expires_in": 900,
                                            "user": {
                                                "id": 12,
                                                "name": "Ada Worker",
                                                "email": "worker@example.test",
                                                "username": "worker.notifications",
                                                "phone": null,
                                                "avatar": null,
                                                "status": "active",
                                                "two_factor_enabled": false,
                                                "must_change_password": true,
                                                "last_login_at": "2027-07-01T09:00:00+00:00",
                                                "created_at": "2027-07-01T08:00:00+00:00",
                                                "updated_at": "2027-07-01T09:00:00+00:00",
                                                "tenant_memberships": [
                                                    {
                                                        "id": 7,
                                                        "status": "active",
                                                        "tenant": {
                                                            "id": 1,
                                                            "uuid": "c14db530-179d-48c7-94f4-ea58b66e4201",
                                                            "name": "Demo Tenant",
                                                            "slug": "demo",
                                                            "code": "DEMO",
                                                            "status": "active",
                                                            "plan": null,
                                                            "currency": "NGN",
                                                            "country": "NG",
                                                            "timezone": "Africa/Lagos",
                                                            "logo_url": null,
                                                            "flag": "🇳🇬"
                                                        },
                                                        "role": {
                                                            "id": 6,
                                                            "name": "Crew Member",
                                                            "slug": "field-worker",
                                                            "scope": "tenant"
                                                        }
                                                    }
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "challenge": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    },
                                    "invalidCode": {
                                        "value": {
                                            "status": "error",
                                            "code": "otp_invalid",
                                            "message": "That code is incorrect. 4 attempts left."
                                        }
                                    },
                                    "expiredCode": {
                                        "value": {
                                            "status": "error",
                                            "code": "otp_expired",
                                            "message": "This code has expired. Sign in again."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Send challenge and the six-digit code emailed after temporary-password login. Returns a 15-minute token for setting your permanent password. Use it with PUT /mobile/auth/password.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/auth/logout": {
            "post": {
                "summary": "Sign out of this device",
                "tags": [
                    "Login"
                ],
                "operationId": "authMobileLogout",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "fid": {
                                        "type": "string",
                                        "nullable": true,
                                        "description": "min: 20; max: 255"
                                    }
                                }
                            },
                            "example": {
                                "fid": "FIREBASE_INSTALLATION_ID"
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Revoke the current bearer token. Send fid to also unregister push notifications for this Firebase installation.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "loggedOut": {
                                        "value": {
                                            "status": "success",
                                            "message": "Logged out successfully."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid credentials or expired bearer token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "fid": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Revoke the current bearer token. Send fid to also unregister push notifications for this Firebase installation.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/auth/password": {
            "put": {
                "summary": "Set or change your password",
                "tags": [
                    "Passwords"
                ],
                "operationId": "accountChangePassword",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "current_password": {
                                        "type": "string"
                                    },
                                    "password": {
                                        "type": "string"
                                    },
                                    "password_confirmation": {
                                        "type": "string"
                                    },
                                    "resetToken": {
                                        "type": "string",
                                        "description": "max: 255"
                                    }
                                },
                                "required": [
                                    "password",
                                    "password_confirmation"
                                ],
                                "anyOf": [
                                    {
                                        "title": "First login with verified onboarding token",
                                        "required": [
                                            "password",
                                            "password_confirmation"
                                        ]
                                    },
                                    {
                                        "title": "Later change with fresh OTP proof",
                                        "required": [
                                            "current_password",
                                            "resetToken",
                                            "password",
                                            "password_confirmation"
                                        ]
                                    }
                                ]
                            },
                            "examples": {
                                "firstLogin": {
                                    "summary": "After first-login OTP verification",
                                    "value": {
                                        "password": "NewPassword2!",
                                        "password_confirmation": "NewPassword2!"
                                    }
                                },
                                "laterChange": {
                                    "summary": "After verifying a fresh password-change OTP",
                                    "value": {
                                        "current_password": "YOUR_CURRENT_PASSWORD",
                                        "resetToken": "VERIFIED_PASSWORD_CHANGE_TOKEN",
                                        "password": "NewPassword2!",
                                        "password_confirmation": "NewPassword2!"
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "First setup: send password and password_confirmation with the token from first-login OTP verification. Later changes: also send current_password and the resetToken from password-change OTP verification. Returns a full-access token and revokes previous tokens.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "passwordSaved": {
                                        "value": {
                                            "status": "success",
                                            "message": "Authentication successful.",
                                            "access_token": "FULL_ACCESS_TOKEN",
                                            "token_type": "Bearer",
                                            "onboarding": {
                                                "enforced": false,
                                                "enforcement": "none",
                                                "managedBy": "tenant_admin",
                                                "requiresSetup": false,
                                                "setupComplete": false,
                                                "profileIncomplete": true,
                                                "nextStep": "phone",
                                                "canUploadIdentityImage": true,
                                                "canSubmit": true,
                                                "status": "incomplete",
                                                "submittedAt": null
                                            },
                                            "user": {
                                                "id": 12,
                                                "name": "Ada Worker",
                                                "email": "worker@example.test",
                                                "username": "worker.notifications",
                                                "phone": null,
                                                "avatar": null,
                                                "status": "active",
                                                "two_factor_enabled": false,
                                                "must_change_password": false,
                                                "last_login_at": "2027-07-01T09:00:00+00:00",
                                                "created_at": "2027-07-01T08:00:00+00:00",
                                                "updated_at": "2027-07-01T09:00:00+00:00",
                                                "tenant_memberships": [
                                                    {
                                                        "id": 7,
                                                        "status": "active",
                                                        "tenant": {
                                                            "id": 1,
                                                            "uuid": "c14db530-179d-48c7-94f4-ea58b66e4201",
                                                            "name": "Demo Tenant",
                                                            "slug": "demo",
                                                            "code": "DEMO",
                                                            "status": "active",
                                                            "plan": null,
                                                            "currency": "NGN",
                                                            "country": "NG",
                                                            "timezone": "Africa/Lagos",
                                                            "logo_url": null,
                                                            "flag": "🇳🇬"
                                                        },
                                                        "role": {
                                                            "id": 6,
                                                            "name": "Crew Member",
                                                            "slug": "field-worker",
                                                            "scope": "tenant"
                                                        }
                                                    }
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid credentials or expired bearer token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "password": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "First setup: send password and password_confirmation with the token from first-login OTP verification. Later changes: also send current_password and the resetToken from password-change OTP verification. Returns a full-access token and revokes previous tokens.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/auth/password/request-otp": {
            "post": {
                "summary": "Request a password-change code",
                "tags": [
                    "Passwords"
                ],
                "operationId": "mobilePasswordRecoveryRequestChange",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "current_password": {
                                        "type": "string"
                                    }
                                },
                                "required": [
                                    "current_password"
                                ]
                            },
                            "example": {
                                "current_password": "YOUR_CURRENT_PASSWORD"
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Send current_password with your bearer token. Emails a code and returns the challenge needed to verify the password change.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "challengeIssued": {
                                        "value": {
                                            "status": "success",
                                            "challenge": "OPAQUE_CHALLENGE",
                                            "expiresIn": 600,
                                            "resendIn": 60,
                                            "message": "If this account has an eligible email address, a code is on its way."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid credentials or expired bearer token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "current_password": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Code delivery or streaming is unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "unavailable": {
                                        "value": {
                                            "status": "error",
                                            "message": "The service is temporarily unavailable."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Send current_password with your bearer token. Emails a code and returns the challenge needed to verify the password change.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/auth/password/resend-otp": {
            "post": {
                "summary": "Resend a password-change code",
                "tags": [
                    "Passwords"
                ],
                "operationId": "mobilePasswordRecoveryResendChange",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "challenge": {
                                        "type": "string",
                                        "description": "max: 255"
                                    }
                                },
                                "required": [
                                    "challenge"
                                ]
                            },
                            "example": {
                                "challenge": "CHALLENGE_FROM_PREVIOUS_RESPONSE"
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Send the password-change challenge. Emails a replacement code after the resend cooldown.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "resent": {
                                        "value": {
                                            "status": "success",
                                            "expiresIn": 600,
                                            "resendIn": 60
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid credentials or expired bearer token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "challenge": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    },
                                    "cooldown": {
                                        "value": {
                                            "status": "error",
                                            "code": "otp_cooldown",
                                            "resendIn": 45
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Send the password-change challenge. Emails a replacement code after the resend cooldown.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/auth/password/verify-otp": {
            "post": {
                "summary": "Verify a password-change code",
                "tags": [
                    "Passwords"
                ],
                "operationId": "mobilePasswordRecoveryVerifyChange",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "challenge": {
                                        "type": "string",
                                        "description": "max: 255"
                                    },
                                    "code": {
                                        "type": "integer"
                                    }
                                },
                                "required": [
                                    "challenge",
                                    "code"
                                ]
                            },
                            "example": {
                                "challenge": "CHALLENGE_FROM_PREVIOUS_RESPONSE",
                                "code": "123456"
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Send challenge and code. Returns the single-use resetToken required by PUT /mobile/auth/password.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "verified": {
                                        "value": {
                                            "status": "success",
                                            "resetToken": "SINGLE_USE_RESET_TOKEN",
                                            "expiresIn": 900
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid credentials or expired bearer token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "challenge": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    },
                                    "invalidCode": {
                                        "value": {
                                            "status": "error",
                                            "code": "otp_invalid",
                                            "message": "That code is incorrect. 4 attempts left."
                                        }
                                    },
                                    "expiredCode": {
                                        "value": {
                                            "status": "error",
                                            "code": "otp_expired",
                                            "message": "This code has expired. Sign in again."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Send challenge and code. Returns the single-use resetToken required by PUT /mobile/auth/password.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/auth/refresh": {
            "post": {
                "summary": "Refresh your bearer token",
                "tags": [
                    "Login"
                ],
                "operationId": "authMobileRefresh",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Send your current bearer token. Returns a replacement token; save it for subsequent requests.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "refreshed": {
                                        "value": {
                                            "status": "success",
                                            "message": "Token refreshed successfully.",
                                            "access_token": "FULL_ACCESS_TOKEN",
                                            "token_type": "Bearer",
                                            "onboarding": {
                                                "enforced": false,
                                                "enforcement": "none",
                                                "managedBy": "tenant_admin",
                                                "requiresSetup": false,
                                                "setupComplete": false,
                                                "profileIncomplete": true,
                                                "nextStep": "phone",
                                                "canUploadIdentityImage": true,
                                                "canSubmit": true,
                                                "status": "incomplete",
                                                "submittedAt": null
                                            },
                                            "user": {
                                                "id": 12,
                                                "name": "Ada Worker",
                                                "email": "worker@example.test",
                                                "username": "worker.notifications",
                                                "phone": null,
                                                "avatar": null,
                                                "status": "active",
                                                "two_factor_enabled": false,
                                                "must_change_password": false,
                                                "last_login_at": "2027-07-01T09:00:00+00:00",
                                                "created_at": "2027-07-01T08:00:00+00:00",
                                                "updated_at": "2027-07-01T09:00:00+00:00",
                                                "tenant_memberships": [
                                                    {
                                                        "id": 7,
                                                        "status": "active",
                                                        "tenant": {
                                                            "id": 1,
                                                            "uuid": "c14db530-179d-48c7-94f4-ea58b66e4201",
                                                            "name": "Demo Tenant",
                                                            "slug": "demo",
                                                            "code": "DEMO",
                                                            "status": "active",
                                                            "plan": null,
                                                            "currency": "NGN",
                                                            "country": "NG",
                                                            "timezone": "Africa/Lagos",
                                                            "logo_url": null,
                                                            "flag": "🇳🇬"
                                                        },
                                                        "role": {
                                                            "id": 6,
                                                            "name": "Crew Member",
                                                            "slug": "field-worker",
                                                            "scope": "tenant"
                                                        }
                                                    }
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid credentials or expired bearer token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    },
                                    "setupRequired": {
                                        "value": {
                                            "status": "error",
                                            "code": "password_change_required",
                                            "message": "Replace your temporary password to continue."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "perPage": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Send your current bearer token. Returns a replacement token; save it for subsequent requests.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/auth/reset-password": {
            "post": {
                "summary": "Reset your forgotten password",
                "tags": [
                    "Passwords"
                ],
                "operationId": "mobilePasswordRecoveryReset",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "login": {
                                        "type": "string",
                                        "description": "max: 255"
                                    },
                                    "password": {
                                        "type": "string"
                                    },
                                    "password_confirmation": {
                                        "type": "string"
                                    },
                                    "resetToken": {
                                        "type": "string",
                                        "description": "max: 255"
                                    }
                                },
                                "required": [
                                    "login",
                                    "password",
                                    "password_confirmation",
                                    "resetToken"
                                ]
                            },
                            "example": {
                                "login": "worker.notifications",
                                "resetToken": "VERIFIED_RESET_TOKEN",
                                "password": "NewPassword2!",
                                "password_confirmation": "NewPassword2!"
                            }
                        }
                    }
                },
                "security": [],
                "responses": {
                    "200": {
                        "description": "Send login, resetToken, password and password_confirmation after recovery-code verification. Resets the password and revokes existing sessions; sign in again afterward.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "passwordReset": {
                                        "value": {
                                            "status": "success",
                                            "message": "Your password has been reset. Please sign in again."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "login": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Send login, resetToken, password and password_confirmation after recovery-code verification. Resets the password and revokes existing sessions; sign in again afterward.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/certificate-issuers": {
            "get": {
                "summary": "List active certificate issuers",
                "tags": [
                    "Certificates"
                ],
                "operationId": "certificateIssuerIndex",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Return the active issuers configured by your tenant. Use an issuer name from this list when uploading a certificate.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": [
                                                {
                                                    "id": "1",
                                                    "name": "Training Provider",
                                                    "isActive": true
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Worker bearer token required."
                    },
                    "403": {
                        "description": "Active worker membership and completed password setup are required."
                    }
                },
                "description": "Return the active issuers configured by your tenant. Use an issuer name from this list when uploading a certificate.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/certificate-qualifications": {
            "get": {
                "summary": "List active certificate qualifications",
                "tags": [
                    "Certificates"
                ],
                "operationId": "certificateQualificationIndex",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Return active tenant qualifications with their issuer IDs and names. Qualifications from inactive issuers are excluded.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "data": [
                                                {
                                                    "id": "2",
                                                    "issuerId": "1",
                                                    "issuerName": "Training Provider",
                                                    "name": "First Aid",
                                                    "description": null,
                                                    "isActive": true
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Worker bearer token required."
                    },
                    "403": {
                        "description": "Active worker membership and completed password setup are required."
                    }
                },
                "description": "Return active tenant qualifications with their issuer IDs and names. Qualifications from inactive issuers are excluded.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/certifications": {
            "get": {
                "summary": "List your certificates and eligibility",
                "tags": [
                    "Certificates"
                ],
                "operationId": "myCertificationIndex",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Current certificates, renewal history and eligibility requirements.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "current": [
                                                    {
                                                        "id": "8",
                                                        "kind": "certificate",
                                                        "employeeId": "3",
                                                        "uploadedBy": 12,
                                                        "certificationName": "First Aid",
                                                        "issuer": "Training Provider",
                                                        "verificationStatus": "pending",
                                                        "evidence": {
                                                            "name": "certificate.pdf",
                                                            "url": "mobile/certifications/8/evidence"
                                                        }
                                                    }
                                                ],
                                                "history": [],
                                                "eligibility": {
                                                    "eligible": false,
                                                    "requirements": []
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired bearer token."
                    },
                    "403": {
                        "description": "The worker account is inactive or must complete password setup."
                    },
                    "404": {
                        "description": "The requested record does not belong to this worker."
                    },
                    "422": {
                        "description": "Missing certificate details or evidence, invalid dates, or unsupported evidence file."
                    }
                },
                "description": "Return your current certificates, renewal history and eligibility against the requirements for your role and project.",
                "x-generated": true
            },
            "post": {
                "summary": "Upload a certificate for verification",
                "tags": [
                    "Certificates"
                ],
                "operationId": "myCertificationStore",
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "certificationName": {
                                        "type": "string",
                                        "description": "max: 255"
                                    },
                                    "credentialType": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "evidence": {
                                        "type": "string",
                                        "format": "binary",
                                        "description": "max: 2048"
                                    },
                                    "expiresAt": {
                                        "type": "string",
                                        "nullable": true,
                                        "format": "date"
                                    },
                                    "identifier": {
                                        "type": "string",
                                        "nullable": true,
                                        "description": "max: 100"
                                    },
                                    "issuedAt": {
                                        "type": "string",
                                        "nullable": true,
                                        "format": "date"
                                    },
                                    "issuer": {
                                        "type": "string",
                                        "description": "max: 255"
                                    },
                                    "renews": {
                                        "type": "integer",
                                        "nullable": true
                                    }
                                },
                                "required": [
                                    "certificationName",
                                    "evidence",
                                    "issuer"
                                ]
                            },
                            "example": {
                                "certificationName": "First Aid",
                                "issuer": "Training Provider",
                                "expiresAt": "2027-11-04",
                                "evidence": "(binary PDF or image)"
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Certificate saved as pending verification, with the evidence download URL.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "8",
                                                "kind": "certificate",
                                                "employeeId": "3",
                                                "uploadedBy": 12,
                                                "certificationName": "First Aid",
                                                "issuer": "Training Provider",
                                                "verificationStatus": "pending",
                                                "evidence": {
                                                    "name": "certificate.pdf",
                                                    "url": "mobile/certifications/8/evidence"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired bearer token."
                    },
                    "403": {
                        "description": "The worker account is inactive or must complete password setup."
                    },
                    "404": {
                        "description": "The requested record does not belong to this worker."
                    },
                    "422": {
                        "description": "Missing certificate details or evidence, invalid dates, or unsupported evidence file."
                    },
                    "503": {
                        "description": "Malware scanning or private storage is unavailable; submission failed. Keep the draft and retry after service recovery.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "scannerUnavailable": {
                                        "value": {
                                            "message": "Document scanning is temporarily unavailable. Your file was not saved. Please try again later."
                                        }
                                    },
                                    "storageUnavailable": {
                                        "value": {
                                            "message": "Cloudinary storage is temporarily unavailable. Please try again later."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Send certificationName, issuer and evidence as multipart form-data. Optional issuedAt, expiresAt and renews describe the credential or its renewal. The certificate is saved against your employee record with verificationStatus=pending.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/certifications/{certification}/evidence": {
            "get": {
                "summary": "Download your certificate evidence",
                "tags": [
                    "Certificates"
                ],
                "operationId": "certificationEvidence",
                "parameters": [
                    {
                        "name": "certification",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Use a certificate ID from your certificate list. Returns the submitted evidence file; another employee’s certificate returns 404.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Authentication required."
                    },
                    "403": {
                        "description": "Worker account is not eligible."
                    },
                    "404": {
                        "description": "File not found or owned by another employee."
                    }
                },
                "description": "Use a certificate ID from your certificate list. Returns the submitted evidence file; another employee’s certificate returns 404.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/currency": {
            "get": {
                "summary": "Read company currency",
                "tags": [
                    "Profile"
                ],
                "operationId": "currencyShow",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Return the shared company currency, selection source, country and country default for payroll and monetary displays. Workers cannot change the company currency.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "data": {
                                                "currency": "NGN",
                                                "source": "country",
                                                "country": "Nigeria",
                                                "countryDefault": "NGN"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Worker bearer token required."
                    },
                    "403": {
                        "description": "Active worker membership and completed password setup are required."
                    }
                },
                "description": "Return the shared company currency, selection source, country and country default for payroll and monetary displays. Workers cannot change the company currency.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/daily-progress": {
            "get": {
                "summary": "List your daily progress reports",
                "tags": [
                    "Daily Progress"
                ],
                "operationId": "mobileDailyProgressIndex",
                "parameters": [
                    {
                        "name": "perPage",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "description": "min: 1; max: 100"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Progress report details, project, review status and photo URLs.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "current_page": 1,
                                                "data": [
                                                    {
                                                        "id": "10",
                                                        "employeeId": 3,
                                                        "submittedBy": 12,
                                                        "projectId": 2,
                                                        "description": "Installed scaffold on the north elevation.",
                                                        "workDate": "2026-11-04",
                                                        "status": "Pending",
                                                        "resubmissionCount": 0,
                                                        "resubmittedAt": null,
                                                        "timelineUrl": "mobile/daily-progress/10/timeline",
                                                        "photos": 1,
                                                        "photoUrls": [
                                                            "mobile/daily-progress/10/photos/1"
                                                        ]
                                                    }
                                                ],
                                                "first_page_url": "/api/v1/mobile/leave-requests?page=1",
                                                "from": 1,
                                                "last_page": 1,
                                                "last_page_url": "/api/v1/mobile/leave-requests?page=1",
                                                "links": [
                                                    {
                                                        "url": null,
                                                        "label": "&laquo; Previous",
                                                        "active": false
                                                    },
                                                    {
                                                        "url": "/api/v1/mobile/leave-requests?page=1",
                                                        "label": "1",
                                                        "active": true
                                                    },
                                                    {
                                                        "url": null,
                                                        "label": "Next &raquo;",
                                                        "active": false
                                                    }
                                                ],
                                                "next_page_url": null,
                                                "path": "/api/v1/mobile/leave-requests",
                                                "per_page": 25,
                                                "prev_page_url": null,
                                                "to": 1,
                                                "total": 1
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired bearer token."
                    },
                    "403": {
                        "description": "The worker account is inactive or must complete password setup."
                    },
                    "404": {
                        "description": "The requested record does not belong to this worker."
                    },
                    "422": {
                        "description": "Unassigned project, invalid work date, missing description or photos, or invalid labour details."
                    }
                },
                "description": "Return your progress reports with project, work date, description, review status and photo URLs. Use perPage to set the page size.",
                "x-generated": true
            },
            "post": {
                "summary": "Submit a daily progress report",
                "tags": [
                    "Daily Progress"
                ],
                "operationId": "mobileDailyProgressStore",
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "costCode": {
                                        "type": "string",
                                        "nullable": true,
                                        "description": "max: 50"
                                    },
                                    "description": {
                                        "type": "string",
                                        "description": "max: 5000"
                                    },
                                    "hours": {
                                        "type": "number",
                                        "nullable": true,
                                        "description": "min: 0.01; max: 24"
                                    },
                                    "photos": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "format": "binary",
                                            "description": "max: 2048"
                                        },
                                        "description": "min: 1; max: 10"
                                    },
                                    "projectId": {
                                        "type": "integer"
                                    },
                                    "workDate": {
                                        "type": "string",
                                        "format": "date"
                                    }
                                },
                                "required": [
                                    "description",
                                    "photos",
                                    "projectId",
                                    "workDate"
                                ]
                            },
                            "example": {
                                "projectId": 2,
                                "workDate": "2026-11-04",
                                "description": "Installed scaffold",
                                "photos": [
                                    "(binary image)"
                                ]
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Progress report details, project, review status and photo URLs.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "10",
                                                "employeeId": 3,
                                                "submittedBy": 12,
                                                "projectId": 2,
                                                "description": "Installed scaffold on the north elevation.",
                                                "workDate": "2026-11-04",
                                                "status": "Pending",
                                                "resubmissionCount": 0,
                                                "resubmittedAt": null,
                                                "timelineUrl": "mobile/daily-progress/10/timeline",
                                                "photos": 1,
                                                "photoUrls": [
                                                    "mobile/daily-progress/10/photos/1"
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired bearer token."
                    },
                    "403": {
                        "description": "The worker account is inactive or must complete password setup."
                    },
                    "404": {
                        "description": "The requested record does not belong to this worker."
                    },
                    "422": {
                        "description": "Unassigned project, invalid work date, missing description or photos, or invalid labour details."
                    },
                    "503": {
                        "description": "Malware scanning or private storage is unavailable; submission failed. Keep the draft and retry after service recovery.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "scannerUnavailable": {
                                        "value": {
                                            "message": "Document scanning is temporarily unavailable. Your file was not saved. Please try again later."
                                        }
                                    },
                                    "storageUnavailable": {
                                        "value": {
                                            "message": "Cloudinary storage is temporarily unavailable. Please try again later."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Send projectId, workDate, description and at least one photos[] image as multipart form-data. Choose a project from daily-progress/projects. Optional hours and costCode add labour detail. Saves the report as Pending and notifies tenant admins.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/daily-progress/projects": {
            "get": {
                "summary": "List projects available for progress reports",
                "tags": [
                    "Daily Progress"
                ],
                "operationId": "mobileDailyProgressProjects",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "IDs and names of your assigned projects.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": [
                                                {
                                                    "id": 2,
                                                    "name": "Assigned site"
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired bearer token."
                    },
                    "403": {
                        "description": "The worker account is inactive or must complete password setup."
                    },
                    "404": {
                        "description": "The requested record does not belong to this worker."
                    },
                    "422": {
                        "description": "Unassigned project, invalid work date, missing description or photos, or invalid labour details."
                    }
                },
                "description": "Return the projects assigned directly to you, through your crew or through a current or upcoming shift.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/daily-progress/{fieldUpdate}": {
            "get": {
                "summary": "Get your daily progress report",
                "tags": [
                    "Daily Progress"
                ],
                "operationId": "mobileDailyProgressShow",
                "parameters": [
                    {
                        "name": "fieldUpdate",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Progress report details, project, review status and photo URLs.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "10",
                                                "employeeId": 3,
                                                "submittedBy": 12,
                                                "projectId": 2,
                                                "description": "Installed scaffold on the north elevation.",
                                                "workDate": "2026-11-04",
                                                "status": "Pending",
                                                "resubmissionCount": 0,
                                                "resubmittedAt": null,
                                                "timelineUrl": "mobile/daily-progress/10/timeline",
                                                "photos": 1,
                                                "photoUrls": [
                                                    "mobile/daily-progress/10/photos/1"
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired bearer token."
                    },
                    "403": {
                        "description": "The worker account is inactive or must complete password setup."
                    },
                    "404": {
                        "description": "The requested record does not belong to this worker."
                    },
                    "422": {
                        "description": "Unassigned project, invalid work date, missing description or photos, or invalid labour details."
                    }
                },
                "description": "Return the selected report’s project, description, photos, review status, reviewer and review date. Another employee’s report returns 404.",
                "x-generated": true
            },
            "patch": {
                "summary": "Correct your daily progress report",
                "tags": [
                    "Daily Progress"
                ],
                "operationId": "dailyUpdateDraftUpdate",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "revision": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "description": "Expected current revision; stale revisions return 409."
                                    },
                                    "description": {
                                        "type": "string",
                                        "minLength": 1,
                                        "maxLength": 5000
                                    },
                                    "workDate": {
                                        "type": "string",
                                        "format": "date"
                                    },
                                    "hours": {
                                        "type": "number",
                                        "nullable": true,
                                        "minimum": 0.01,
                                        "maximum": 24
                                    },
                                    "costCode": {
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 50
                                    }
                                }
                            },
                            "example": {
                                "description": "Completed scaffold on the north elevation",
                                "revision": 3
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "fieldUpdate",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Progress report details, project, review status and photo URLs.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "10",
                                                "employeeId": 3,
                                                "submittedBy": 12,
                                                "projectId": 2,
                                                "description": "Installed scaffold on the north elevation.",
                                                "workDate": "2026-11-04",
                                                "status": "Pending",
                                                "resubmissionCount": 0,
                                                "resubmittedAt": null,
                                                "timelineUrl": "mobile/daily-progress/10/timeline",
                                                "photos": 1,
                                                "photoUrls": [
                                                    "mobile/daily-progress/10/photos/1"
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired bearer token."
                    },
                    "403": {
                        "description": "The worker account is inactive or must complete password setup."
                    },
                    "404": {
                        "description": "The requested record does not belong to this worker."
                    },
                    "422": {
                        "description": "Unassigned project, invalid work date, missing description or photos, or invalid labour details."
                    },
                    "409": {
                        "description": "The revision is stale. Reload the report before saving or resubmitting."
                    }
                },
                "description": "Send description and optionally workDate, hours, costCode and revision. Hours and costCode may be omitted or null. Only your draft, rejected report or pending report awaiting evidence can be edited. Saves corrections without resubmitting; previous rejection reasons and content remain in history. A stale revision returns 409.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/daily-progress/{fieldUpdate}/history": {
            "get": {
                "summary": "Read your daily progress timeline",
                "tags": [
                    "Daily Progress"
                ],
                "operationId": "fieldUpdateHistory",
                "parameters": [
                    {
                        "name": "fieldUpdate",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Chronological report events; previous rejection reasons and content survive resubmission.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "data": [
                                                {
                                                    "id": 12,
                                                    "action": "rejected",
                                                    "revision": 3,
                                                    "actor": {
                                                        "id": 7,
                                                        "name": "Supervisor"
                                                    },
                                                    "at": "2026-11-15T09:00:00Z",
                                                    "snapshot": {
                                                        "status": "Rejected",
                                                        "reason": "Describe the completed work",
                                                        "update_text": "Scaffold work",
                                                        "hours": null,
                                                        "cost_code": null,
                                                        "photos": [
                                                            {
                                                                "id": 4
                                                            }
                                                        ]
                                                    }
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired bearer token."
                    },
                    "403": {
                        "description": "The worker account is inactive or must complete password setup."
                    },
                    "404": {
                        "description": "The requested record does not belong to this worker."
                    },
                    "422": {
                        "description": "Unassigned project, invalid work date, missing description or photos, or invalid labour details."
                    }
                },
                "description": "Return all events in chronological order, including submissions, rejections, edits, photo additions, resubmissions and approval. Each event includes its actor, timestamp, revision and content snapshot. Rejection snapshots retain their original reasons after resubmission. Only your own report is accessible.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/daily-progress/{fieldUpdate}/photos": {
            "post": {
                "summary": "Add evidence to your progress report",
                "tags": [
                    "Daily Progress"
                ],
                "operationId": "fieldUpdatePhotoStore",
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "photos": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "format": "binary",
                                            "description": "max: 2048"
                                        },
                                        "description": "min: 1; max: 10"
                                    }
                                },
                                "required": [
                                    "photos"
                                ]
                            },
                            "example": {
                                "photos": [
                                    "(binary image)"
                                ]
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "fieldUpdate",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Progress report details, project, review status and photo URLs.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "10",
                                                "employeeId": 3,
                                                "submittedBy": 12,
                                                "projectId": 2,
                                                "description": "Installed scaffold on the north elevation.",
                                                "workDate": "2026-11-04",
                                                "status": "Pending",
                                                "resubmissionCount": 0,
                                                "resubmittedAt": null,
                                                "timelineUrl": "mobile/daily-progress/10/timeline",
                                                "photos": 1,
                                                "photoUrls": [
                                                    "mobile/daily-progress/10/photos/1"
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired bearer token."
                    },
                    "403": {
                        "description": "The worker account is inactive or must complete password setup."
                    },
                    "404": {
                        "description": "The requested record does not belong to this worker."
                    },
                    "422": {
                        "description": "Unassigned project, invalid work date, missing description or photos, or invalid labour details."
                    },
                    "503": {
                        "description": "Malware scanning or private storage is unavailable; submission failed. Keep the draft and retry after service recovery.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "scannerUnavailable": {
                                        "value": {
                                            "message": "Document scanning is temporarily unavailable. Your file was not saved. Please try again later."
                                        }
                                    },
                                    "storageUnavailable": {
                                        "value": {
                                            "message": "Cloudinary storage is temporarily unavailable. Please try again later."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "The report is approved and its evidence is locked."
                    }
                },
                "description": "Send one to ten photos[] images as multipart form-data. You must own or have submitted the report; approved reports are locked.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/daily-progress/{fieldUpdate}/photos/{photo}": {
            "get": {
                "summary": "Download a progress report photo",
                "tags": [
                    "Daily Progress"
                ],
                "operationId": "fieldUpdatePhotoShow",
                "parameters": [
                    {
                        "name": "fieldUpdate",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "photo",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Return a photo attached to your progress report. Both the report and photo IDs must match.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Authentication required."
                    },
                    "403": {
                        "description": "Worker account is not eligible."
                    },
                    "404": {
                        "description": "File not found or owned by another employee."
                    }
                },
                "description": "Return a photo attached to your progress report. Both the report and photo IDs must match.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/daily-progress/{fieldUpdate}/submit": {
            "post": {
                "summary": "Resubmit your daily progress report",
                "tags": [
                    "Daily Progress"
                ],
                "operationId": "dailyUpdateSubmitSubmit",
                "parameters": [
                    {
                        "name": "fieldUpdate",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "401": {
                        "description": "Missing or expired bearer token."
                    },
                    "403": {
                        "description": "The worker account is inactive or must complete password setup."
                    },
                    "404": {
                        "description": "The requested record does not belong to this worker."
                    },
                    "422": {
                        "description": "Unassigned project, invalid work date, missing description or photos, or invalid labour details."
                    },
                    "503": {
                        "description": "Malware scanning or private storage is unavailable; submission failed. Keep the draft and retry after service recovery.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "scannerUnavailable": {
                                        "value": {
                                            "message": "Document scanning is temporarily unavailable. Your file was not saved. Please try again later."
                                        }
                                    },
                                    "storageUnavailable": {
                                        "value": {
                                            "message": "Cloudinary storage is temporarily unavailable. Please try again later."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "200": {
                        "description": "The same report returns to Pending review. Hours and cost code remain optional.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "10",
                                                "status": "Pending",
                                                "revision": 5,
                                                "hours": null,
                                                "costCode": null,
                                                "canEdit": false,
                                                "canResubmit": false,
                                                "resubmissionCount": 1,
                                                "resubmittedAt": "2026-11-16T09:00:00Z"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "The revision is stale. Reload the report before saving or resubmitting."
                    }
                },
                "description": "Optionally send revision. Requires description and at least one photo; hours and costCode are optional. Requested evidence requires a new photo. Returns the same report as Pending with resubmissionCount and resubmittedAt, and sends reviewers a distinct resubmission notification linked to the report. All previous rejections and submissions remain in history.",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "revision": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "description": "Expected current revision; stale revisions return 409."
                                    }
                                }
                            },
                            "example": {
                                "revision": 4
                            }
                        }
                    }
                },
                "x-generated": true
            }
        },
        "/api/v1/mobile/daily-progress/{fieldUpdate}/timeline": {
            "get": {
                "summary": "Get the daily report timeline tracker",
                "tags": [
                    "Daily Progress"
                ],
                "operationId": "fieldUpdateHistory2",
                "parameters": [
                    {
                        "name": "fieldUpdate",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Server-owned biometric workflow state",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": [
                                                {
                                                    "id": "00000000-0000-4000-8000-000000000001",
                                                    "action": "attendance.rejected",
                                                    "reason": "Reviewer explanation",
                                                    "at": "2026-11-17T16:10:00Z"
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Permission, consent withdrawal or disabled fallback policy."
                    },
                    "409": {
                        "description": "Expired session, conflicting evidence or stale review."
                    },
                    "422": {
                        "description": "Invalid movement report, consent or image list."
                    },
                    "429": {
                        "description": "Rate limited."
                    }
                },
                "description": "Return reportId, currentStatus, currentStage, resubmissionCount, resubmittedAt and chronological events. Every event includes id, action, label, status, at (ISO 8601 with timezone), actor, reason, revision and isLegacy. Includes repeated rejection/resubmission cycles, approval, sign-off, edits and photo activity. Only actual recorded events appear; historical imports are marked isLegacy. The raw snapshots remain available from the history endpoint. Contract version 2 is additive to v1. Server-issued sessions precede the movement check. Automatic enrollment and attendance acceptance are disabled. Processing captures are polled through the existing owned capture endpoint. Identical evidence retries preserve bytes/report; different evidence returns 409. No vectors or scores are returned to workers.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/documents": {
            "get": {
                "summary": "List your documents",
                "tags": [
                    "Documents"
                ],
                "operationId": "mobileDocumentIndex",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Documents attached to your employee record.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": [
                                                {
                                                    "id": "7",
                                                    "kind": "document",
                                                    "employeeId": 3,
                                                    "uploadedBy": 12,
                                                    "name": "supporting.pdf",
                                                    "category": "Supporting",
                                                    "uploadedAt": "2026-11-04T10:00:00+00:00",
                                                    "fileType": "PDF",
                                                    "downloadUrl": "/api/v1/mobile/documents/7/download"
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired bearer token."
                    },
                    "403": {
                        "description": "The worker account is inactive or must complete password setup."
                    },
                    "404": {
                        "description": "The requested record does not belong to this worker."
                    },
                    "422": {
                        "description": "Missing file or category, unsupported file contents, or an attempt to supply ownership fields."
                    }
                },
                "description": "Return documents attached to your employee record, including category, uploader, upload date and download URL.",
                "x-generated": true
            },
            "post": {
                "summary": "Upload a personal document",
                "tags": [
                    "Documents"
                ],
                "operationId": "mobileDocumentStore",
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "category": {
                                        "type": "string",
                                        "enum": [
                                            "Personal",
                                            "Identification",
                                            "Supporting",
                                            "Others"
                                        ]
                                    },
                                    "file": {
                                        "type": "string",
                                        "format": "binary",
                                        "description": "max: 2048"
                                    }
                                },
                                "required": [
                                    "category",
                                    "file"
                                ]
                            },
                            "example": {
                                "category": "Supporting",
                                "file": "(binary PDF or image)"
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Saved document with employee ID, uploader, category and download URL.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "7",
                                                "kind": "document",
                                                "employeeId": 3,
                                                "uploadedBy": 12,
                                                "name": "supporting.pdf",
                                                "category": "Supporting",
                                                "uploadedAt": "2026-11-04T10:00:00+00:00",
                                                "fileType": "PDF",
                                                "downloadUrl": "/api/v1/mobile/documents/7/download"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired bearer token."
                    },
                    "403": {
                        "description": "The worker account is inactive or must complete password setup."
                    },
                    "404": {
                        "description": "The requested record does not belong to this worker."
                    },
                    "422": {
                        "description": "Missing file or category, unsupported file contents, or an attempt to supply ownership fields."
                    },
                    "503": {
                        "description": "Malware scanning or private storage is unavailable; submission failed. Keep the draft and retry after service recovery.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "scannerUnavailable": {
                                        "value": {
                                            "message": "Document scanning is temporarily unavailable. Your file was not saved. Please try again later."
                                        }
                                    },
                                    "storageUnavailable": {
                                        "value": {
                                            "message": "Cloudinary storage is temporarily unavailable. Please try again later."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Send category and file as multipart form-data. The document is attached to your employee record and records your account as uploadedBy.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/documents/{document}/download": {
            "get": {
                "summary": "Download your document",
                "tags": [
                    "Documents"
                ],
                "operationId": "mobileDocumentDownload",
                "parameters": [
                    {
                        "name": "document",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Use a document ID from your document list. Returns the file as a private download; another employee’s document returns 404.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Authentication required."
                    },
                    "403": {
                        "description": "Worker account is not eligible."
                    },
                    "404": {
                        "description": "File not found or owned by another employee."
                    }
                },
                "description": "Use a document ID from your document list. Returns the file as a private download; another employee’s document returns 404.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/emergency-contact": {
            "get": {
                "summary": "Get your emergency contact",
                "tags": [
                    "Profile"
                ],
                "operationId": "mobileEmergencyContactShow",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Return employeeId and emergencyContact with fullName, relationship and phone. emergencyContact is null until a contact is recorded. The employee and tenant are resolved from your worker account.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "savedContact": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "employeeId": 3,
                                                "emergencyContact": {
                                                    "fullName": "Bola Ahmed",
                                                    "relationship": "Sibling",
                                                    "phone": "+234 801 234 5678"
                                                }
                                            }
                                        }
                                    },
                                    "noContact": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "employeeId": 3,
                                                "emergencyContact": null
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid credentials or expired bearer token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    },
                                    "setupRequired": {
                                        "value": {
                                            "status": "error",
                                            "code": "password_change_required",
                                            "message": "Replace your temporary password to continue."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "perPage": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Return employeeId and emergencyContact with fullName, relationship and phone. emergencyContact is null until a contact is recorded. The employee and tenant are resolved from your worker account.",
                "x-generated": true
            },
            "put": {
                "summary": "Save your emergency contact",
                "tags": [
                    "Profile"
                ],
                "operationId": "mobileEmergencyContactUpdate",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "fullName": {
                                        "type": "string",
                                        "description": "max: 255"
                                    },
                                    "phone": {
                                        "type": "string",
                                        "description": "max: 40"
                                    },
                                    "relationship": {
                                        "type": "string",
                                        "description": "max: 100"
                                    }
                                },
                                "required": [
                                    "fullName",
                                    "phone",
                                    "relationship"
                                ]
                            },
                            "example": {
                                "fullName": "Bola Ahmed",
                                "relationship": "Sibling",
                                "phone": "+234 801 234 5678"
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Send fullName, relationship and phone as JSON to create or replace your single emergency contact. All three fields are required. Do not send employee or tenant IDs; the contact is saved on the shared employee record. The worker profile and authorised tenant employee-profile endpoints return the same saved contact. This endpoint remains available during first-time setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "savedContact": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "employeeId": 3,
                                                "emergencyContact": {
                                                    "fullName": "Bola Ahmed",
                                                    "relationship": "Sibling",
                                                    "phone": "+234 801 234 5678"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid credentials or expired bearer token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    },
                                    "setupRequired": {
                                        "value": {
                                            "status": "error",
                                            "code": "password_change_required",
                                            "message": "Replace your temporary password to continue."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "fullName": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Send fullName, relationship and phone as JSON to create or replace your single emergency contact. All three fields are required. Do not send employee or tenant IDs; the contact is saved on the shared employee record. The worker profile and authorised tenant employee-profile endpoints return the same saved contact. This endpoint remains available during first-time setup.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/expenses": {
            "get": {
                "summary": "List your expense claims",
                "tags": [
                    "Expenses"
                ],
                "operationId": "mobileExpenseIndex",
                "parameters": [
                    {
                        "name": "perPage",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "description": "min: 1; max: 100"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Claim details, receipt URLs and dated review progress.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "current_page": 1,
                                                "data": [
                                                    {
                                                        "id": "ac514e17-6585-4eab-b833-96e67627a39f",
                                                        "reference": "ac514e17-6585-4eab-b833-96e67627a39f",
                                                        "employeeId": 3,
                                                        "submittedBy": 12,
                                                        "category": "Others",
                                                        "amount": 2500,
                                                        "notes": "Replacement safety gloves",
                                                        "status": "Pending",
                                                        "progress": [
                                                            {
                                                                "stage": "sent",
                                                                "at": "2026-11-04T10:00:00+00:00",
                                                                "userId": 12
                                                            }
                                                        ],
                                                        "evidence": [
                                                            {
                                                                "id": "1",
                                                                "uploadedBy": 12,
                                                                "url": "/api/v1/mobile/expenses/ac514e17-6585-4eab-b833-96e67627a39f/evidence/1",
                                                                "originalFilename": "receipt.pdf"
                                                            }
                                                        ]
                                                    }
                                                ],
                                                "first_page_url": "/api/v1/mobile/leave-requests?page=1",
                                                "from": 1,
                                                "last_page": 1,
                                                "last_page_url": "/api/v1/mobile/leave-requests?page=1",
                                                "links": [
                                                    {
                                                        "url": null,
                                                        "label": "&laquo; Previous",
                                                        "active": false
                                                    },
                                                    {
                                                        "url": "/api/v1/mobile/leave-requests?page=1",
                                                        "label": "1",
                                                        "active": true
                                                    },
                                                    {
                                                        "url": null,
                                                        "label": "Next &raquo;",
                                                        "active": false
                                                    }
                                                ],
                                                "next_page_url": null,
                                                "path": "/api/v1/mobile/leave-requests",
                                                "per_page": 25,
                                                "prev_page_url": null,
                                                "to": 1,
                                                "total": 1
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired bearer token."
                    },
                    "403": {
                        "description": "The worker account is inactive or must complete password setup."
                    },
                    "404": {
                        "description": "The requested record does not belong to this worker."
                    },
                    "422": {
                        "description": "Invalid category, amount or date; missing or unsupported receipt; or an unassigned project."
                    }
                },
                "description": "Return your claims with category, amount, status, receipt links and dated review progress. Use perPage to set the page size.",
                "x-generated": true
            },
            "post": {
                "summary": "Submit an expense claim",
                "tags": [
                    "Expenses"
                ],
                "operationId": "mobileExpenseStore",
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "amount": {
                                        "type": "number",
                                        "description": "Must satisfy the current tenant claim limit. Enterprise expense policies may lower the maximum."
                                    },
                                    "category": {
                                        "type": "string",
                                        "enum": [
                                            "Travel",
                                            "Transport",
                                            "Fuel",
                                            "Meals",
                                            "Accommodation",
                                            "Materials",
                                            "Equipment",
                                            "Others"
                                        ]
                                    },
                                    "costCodeId": {
                                        "type": "integer",
                                        "nullable": true
                                    },
                                    "expenseDate": {
                                        "type": "string",
                                        "format": "date"
                                    },
                                    "notes": {
                                        "type": "string",
                                        "nullable": true,
                                        "description": "max: 2000"
                                    },
                                    "projectId": {
                                        "type": "integer",
                                        "nullable": true
                                    },
                                    "receipt": {
                                        "type": "string",
                                        "nullable": true,
                                        "format": "binary",
                                        "description": "Required unless the licensed Enterprise expense policy explicitly waives receipts."
                                    }
                                },
                                "required": [
                                    "amount",
                                    "category",
                                    "expenseDate"
                                ]
                            },
                            "example": {
                                "category": "Others",
                                "amount": 2500,
                                "expenseDate": "2026-11-04",
                                "notes": "Replacement safety gloves",
                                "receipt": "(binary image or PDF)"
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Claim details, receipt URLs and dated review progress.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "ac514e17-6585-4eab-b833-96e67627a39f",
                                                "reference": "ac514e17-6585-4eab-b833-96e67627a39f",
                                                "employeeId": 3,
                                                "submittedBy": 12,
                                                "category": "Others",
                                                "amount": 2500,
                                                "notes": "Replacement safety gloves",
                                                "status": "Pending",
                                                "progress": [
                                                    {
                                                        "stage": "sent",
                                                        "at": "2026-11-04T10:00:00+00:00",
                                                        "userId": 12
                                                    }
                                                ],
                                                "evidence": [
                                                    {
                                                        "id": "1",
                                                        "uploadedBy": 12,
                                                        "url": "/api/v1/mobile/expenses/ac514e17-6585-4eab-b833-96e67627a39f/evidence/1",
                                                        "originalFilename": "receipt.pdf"
                                                    }
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired bearer token."
                    },
                    "403": {
                        "description": "The worker account is inactive or must complete password setup."
                    },
                    "404": {
                        "description": "The requested record does not belong to this worker."
                    },
                    "422": {
                        "description": "Invalid category, amount or date; missing or unsupported receipt; or an unassigned project."
                    },
                    "503": {
                        "description": "Malware scanning or private storage is unavailable; submission failed. Keep the draft and retry after service recovery.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "scannerUnavailable": {
                                        "value": {
                                            "message": "Document scanning is temporarily unavailable. Your file was not saved. Please try again later."
                                        }
                                    },
                                    "storageUnavailable": {
                                        "value": {
                                            "message": "Cloudinary storage is temporarily unavailable. Please try again later."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Send category, amount, expenseDate and receipt as multipart form-data. The server generates a UUID returned as id and reference; use it for all claim actions. The receipt must be an image or PDF; notes and an assigned projectId are optional. Saves the claim as Pending and notifies tenant admins.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/expenses/form": {
            "get": {
                "summary": "Get expense categories and projects",
                "tags": [
                    "Expenses"
                ],
                "operationId": "mobileExpenseForm",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Expense categories and your assigned projects.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "categories": [
                                                    "Travel",
                                                    "Transport",
                                                    "Fuel",
                                                    "Meals",
                                                    "Accommodation",
                                                    "Materials",
                                                    "Equipment",
                                                    "Others"
                                                ],
                                                "projects": [
                                                    {
                                                        "id": 2,
                                                        "name": "Assigned site"
                                                    }
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired bearer token."
                    },
                    "403": {
                        "description": "The worker account is inactive or must complete password setup."
                    },
                    "404": {
                        "description": "The requested record does not belong to this worker."
                    },
                    "422": {
                        "description": "Invalid category, amount or date; missing or unsupported receipt; or an unassigned project."
                    }
                },
                "description": "Return the supported expense categories, including Others, and your assigned projects for the claim form.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/expenses/{expense}": {
            "get": {
                "summary": "Get your expense and review progress",
                "tags": [
                    "Expenses"
                ],
                "operationId": "mobileExpenseShow",
                "parameters": [
                    {
                        "name": "expense",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "description": "The claim UUID returned as id/reference. Numeric database IDs are not accepted.",
                        "example": "ac514e17-6585-4eab-b833-96e67627a39f"
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Claim details, receipt URLs and dated review progress.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "ac514e17-6585-4eab-b833-96e67627a39f",
                                                "reference": "ac514e17-6585-4eab-b833-96e67627a39f",
                                                "employeeId": 3,
                                                "submittedBy": 12,
                                                "category": "Others",
                                                "amount": 2500,
                                                "notes": "Replacement safety gloves",
                                                "status": "Pending",
                                                "progress": [
                                                    {
                                                        "stage": "sent",
                                                        "at": "2026-11-04T10:00:00+00:00",
                                                        "userId": 12
                                                    }
                                                ],
                                                "evidence": [
                                                    {
                                                        "id": "1",
                                                        "uploadedBy": 12,
                                                        "url": "/api/v1/mobile/expenses/ac514e17-6585-4eab-b833-96e67627a39f/evidence/1",
                                                        "originalFilename": "receipt.pdf"
                                                    }
                                                ]
                                            }
                                        }
                                    },
                                    "approved": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "ac514e17-6585-4eab-b833-96e67627a39f",
                                                "reference": "ac514e17-6585-4eab-b833-96e67627a39f",
                                                "employeeId": 3,
                                                "submittedBy": 12,
                                                "category": "Others",
                                                "amount": 2500,
                                                "notes": "Replacement safety gloves",
                                                "status": "Approved",
                                                "progress": [
                                                    {
                                                        "stage": "sent",
                                                        "at": "2026-11-04T10:00:00+00:00",
                                                        "userId": 12
                                                    },
                                                    {
                                                        "stage": "reviewed",
                                                        "at": "2026-11-04T11:00:00+00:00",
                                                        "userId": 5
                                                    },
                                                    {
                                                        "stage": "approved",
                                                        "at": "2026-11-04T11:05:00+00:00",
                                                        "userId": 5,
                                                        "reason": null
                                                    }
                                                ],
                                                "evidence": [
                                                    {
                                                        "id": "1",
                                                        "uploadedBy": 12,
                                                        "url": "/api/v1/mobile/expenses/ac514e17-6585-4eab-b833-96e67627a39f/evidence/1",
                                                        "originalFilename": "receipt.pdf"
                                                    }
                                                ],
                                                "reviewedBy": 5
                                            }
                                        }
                                    },
                                    "rejected": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "ac514e17-6585-4eab-b833-96e67627a39f",
                                                "reference": "ac514e17-6585-4eab-b833-96e67627a39f",
                                                "employeeId": 3,
                                                "submittedBy": 12,
                                                "category": "Others",
                                                "amount": 2500,
                                                "notes": "Replacement safety gloves",
                                                "status": "Rejected",
                                                "progress": [
                                                    {
                                                        "stage": "sent",
                                                        "at": "2026-11-04T10:00:00+00:00",
                                                        "userId": 12
                                                    },
                                                    {
                                                        "stage": "reviewed",
                                                        "at": "2026-11-04T11:00:00+00:00",
                                                        "userId": 5
                                                    },
                                                    {
                                                        "stage": "rejected",
                                                        "at": "2026-11-04T11:05:00+00:00",
                                                        "userId": 5,
                                                        "reason": "Not a business expense"
                                                    }
                                                ],
                                                "evidence": [
                                                    {
                                                        "id": "1",
                                                        "uploadedBy": 12,
                                                        "url": "/api/v1/mobile/expenses/ac514e17-6585-4eab-b833-96e67627a39f/evidence/1",
                                                        "originalFilename": "receipt.pdf"
                                                    }
                                                ],
                                                "reviewedBy": 5
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired bearer token."
                    },
                    "403": {
                        "description": "The worker account is inactive or must complete password setup."
                    },
                    "404": {
                        "description": "The requested record does not belong to this worker."
                    },
                    "422": {
                        "description": "Invalid category, amount or date; missing or unsupported receipt; or an unassigned project."
                    }
                },
                "description": "Use the claim UUID returned as id/reference. Return the selected claim’s details, receipt links and dated sent, reviewed and approved/rejected stages. Progress includes the reviewer’s user ID and rejection reason when applicable.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/expenses/{expense}/evidence": {
            "post": {
                "summary": "Add receipts to your expense",
                "tags": [
                    "Expenses"
                ],
                "operationId": "expenseStoreEvidence",
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "evidence": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "format": "binary",
                                            "description": "max: 10240"
                                        },
                                        "description": "min: 1"
                                    }
                                },
                                "required": [
                                    "evidence"
                                ]
                            },
                            "example": {
                                "evidence": [
                                    "(binary image or PDF)"
                                ]
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "expense",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "description": "The claim UUID returned as id/reference. Numeric database IDs are not accepted.",
                        "example": "ac514e17-6585-4eab-b833-96e67627a39f"
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Claim details, receipt URLs and dated review progress.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "ac514e17-6585-4eab-b833-96e67627a39f",
                                                "reference": "ac514e17-6585-4eab-b833-96e67627a39f",
                                                "employeeId": 3,
                                                "submittedBy": 12,
                                                "category": "Others",
                                                "amount": 2500,
                                                "notes": "Replacement safety gloves",
                                                "status": "Pending",
                                                "progress": [
                                                    {
                                                        "stage": "sent",
                                                        "at": "2026-11-04T10:00:00+00:00",
                                                        "userId": 12
                                                    }
                                                ],
                                                "evidence": [
                                                    {
                                                        "id": "1",
                                                        "uploadedBy": 12,
                                                        "url": "/api/v1/mobile/expenses/ac514e17-6585-4eab-b833-96e67627a39f/evidence/1",
                                                        "originalFilename": "receipt.pdf"
                                                    }
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired bearer token."
                    },
                    "403": {
                        "description": "The worker account is inactive or must complete password setup."
                    },
                    "404": {
                        "description": "The requested record does not belong to this worker."
                    },
                    "422": {
                        "description": "Invalid category, amount or date; missing or unsupported receipt; or an unassigned project."
                    },
                    "503": {
                        "description": "Malware scanning or private storage is unavailable; submission failed. Keep the draft and retry after service recovery.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "scannerUnavailable": {
                                        "value": {
                                            "message": "Document scanning is temporarily unavailable. Your file was not saved. Please try again later."
                                        }
                                    },
                                    "storageUnavailable": {
                                        "value": {
                                            "message": "Cloudinary storage is temporarily unavailable. Please try again later."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "The claim is no longer Pending; receipt uploads are locked."
                    }
                },
                "description": "Send evidence[] files as multipart form-data. Only the employee who owns the claim can add receipts, and only while its status is Pending.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/expenses/{expense}/evidence/{evidence}": {
            "get": {
                "summary": "Download your expense receipt",
                "tags": [
                    "Expenses"
                ],
                "operationId": "expenseEvidence",
                "parameters": [
                    {
                        "name": "expense",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "description": "The claim UUID returned as id/reference. Numeric database IDs are not accepted.",
                        "example": "ac514e17-6585-4eab-b833-96e67627a39f"
                    },
                    {
                        "name": "evidence",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Return a receipt attached to your claim. Both the expense and evidence IDs must match; another employee’s receipt returns 404.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Authentication required."
                    },
                    "403": {
                        "description": "Worker account is not eligible."
                    },
                    "404": {
                        "description": "File not found or owned by another employee."
                    }
                },
                "description": "Return a receipt attached to your claim. Both the expense and evidence IDs must match; another employee’s receipt returns 404.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/face/capture-sessions": {
            "post": {
                "summary": "Capture (Face Workflow)",
                "tags": [
                    "Attendance"
                ],
                "operationId": "faceWorkflowCapture",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "action": {
                                        "type": "string",
                                        "enum": [
                                            "enrollment",
                                            "clock_in",
                                            "clock_out"
                                        ]
                                    },
                                    "consentId": {
                                        "type": "string",
                                        "format": "uuid"
                                    }
                                },
                                "required": [
                                    "action",
                                    "consentId"
                                ]
                            },
                            "example": {
                                "action": "clock_in",
                                "consentId": "00000000-0000-4000-8000-000000000001"
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Server-owned biometric workflow state",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "00000000-0000-4000-8000-000000000001",
                                                "action": "clock_in",
                                                "status": "issued",
                                                "contract_version": 2,
                                                "challenges": [
                                                    "blink",
                                                    "look_up",
                                                    "turn_left"
                                                ],
                                                "nonce": "SERVER_ISSUED_NONCE",
                                                "liveness_assurance": "device_reported",
                                                "expires_at": "2026-11-17T08:05:00Z"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Permission, consent withdrawal or disabled fallback policy."
                    },
                    "409": {
                        "description": "Expired session, conflicting evidence or stale review."
                    },
                    "422": {
                        "description": "Invalid movement report, consent or image list."
                    },
                    "429": {
                        "description": "Rate limited."
                    }
                },
                "x-generated": true,
                "description": " Contract version 2 is additive to v1. Server-issued sessions precede the movement check. Automatic enrollment and attendance acceptance are disabled. Processing captures are polled through the existing owned capture endpoint. Identical evidence retries preserve bytes/report; different evidence returns 409. No vectors or scores are returned to workers."
            }
        },
        "/api/v1/mobile/face/capture-sessions/{capture}/evidence": {
            "post": {
                "summary": "Upload (Face Workflow)",
                "tags": [
                    "Attendance"
                ],
                "operationId": "faceWorkflowUpload",
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "photos",
                                    "movementReport"
                                ],
                                "properties": {
                                    "photos": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "format": "binary"
                                        }
                                    },
                                    "movementReport": {
                                        "type": "string",
                                        "description": "JSON containing method=mlkit_movement, methodVersion=1, result=passed, challengeSessionId, nonce and the exact completedChallenges issued by the server. Device report only; never proof of live capture."
                                    }
                                }
                            },
                            "example": {
                                "photos": [
                                    "(binary JPEG)"
                                ],
                                "movementReport": "{\"method\":\"mlkit_movement\",\"methodVersion\":\"1\",\"result\":\"passed\",\"challengeSessionId\":\"00000000-0000-4000-8000-000000000001\",\"nonce\":\"SERVER_ISSUED_NONCE\",\"completedChallenges\":[\"blink\",\"look_up\",\"turn_left\"]}"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "capture",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "202": {
                        "description": "Server-owned biometric workflow state",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "00000000-0000-4000-8000-000000000001",
                                                "status": "processing",
                                                "contract_version": 2,
                                                "liveness_assurance": "device_reported"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Permission, consent withdrawal or disabled fallback policy."
                    },
                    "409": {
                        "description": "Expired session, conflicting evidence or stale review."
                    },
                    "422": {
                        "description": "Invalid movement report, consent or image list."
                    },
                    "429": {
                        "description": "Rate limited."
                    }
                },
                "x-generated": true,
                "description": " Contract version 2 is additive to v1. Server-issued sessions precede the movement check. Automatic enrollment and attendance acceptance are disabled. Processing captures are polled through the existing owned capture endpoint. Identical evidence retries preserve bytes/report; different evidence returns 409. No vectors or scores are returned to workers."
            }
        },
        "/api/v1/mobile/face/consents": {
            "post": {
                "summary": "Consent (Face Workflow)",
                "tags": [
                    "Attendance"
                ],
                "operationId": "faceWorkflowConsent",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "accepted": {
                                        "type": "boolean"
                                    },
                                    "noticeVersion": {
                                        "type": "string",
                                        "description": "max: 100"
                                    }
                                },
                                "required": [
                                    "accepted",
                                    "noticeVersion"
                                ]
                            },
                            "example": {
                                "noticeVersion": "face-v1",
                                "accepted": true
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Server-owned biometric workflow state",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "00000000-0000-4000-8000-000000000001",
                                                "notice_version": "face-v1",
                                                "accepted_at": "2026-11-17T08:00:00Z",
                                                "withdrawn_at": null
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Permission, consent withdrawal or disabled fallback policy."
                    },
                    "409": {
                        "description": "Expired session, conflicting evidence or stale review."
                    },
                    "422": {
                        "description": "Invalid movement report, consent or image list."
                    },
                    "429": {
                        "description": "Rate limited."
                    }
                },
                "x-generated": true,
                "description": " Contract version 2 is additive to v1. Server-issued sessions precede the movement check. Automatic enrollment and attendance acceptance are disabled. Processing captures are polled through the existing owned capture endpoint. Identical evidence retries preserve bytes/report; different evidence returns 409. No vectors or scores are returned to workers."
            }
        },
        "/api/v1/mobile/face/consents/{consent}/withdraw": {
            "post": {
                "summary": "Withdraw (Face Workflow)",
                "tags": [
                    "Attendance"
                ],
                "operationId": "faceWorkflowWithdraw",
                "parameters": [
                    {
                        "name": "consent",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Server-owned biometric workflow state",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Permission, consent withdrawal or disabled fallback policy."
                    },
                    "409": {
                        "description": "Expired session, conflicting evidence or stale review."
                    },
                    "422": {
                        "description": "Invalid movement report, consent or image list."
                    },
                    "429": {
                        "description": "Rate limited."
                    }
                },
                "x-generated": true,
                "requestBody": {
                    "content": {
                        "application/json": {
                            "example": {}
                        }
                    }
                },
                "description": " Contract version 2 is additive to v1. Server-issued sessions precede the movement check. Automatic enrollment and attendance acceptance are disabled. Processing captures are polled through the existing owned capture endpoint. Identical evidence retries preserve bytes/report; different evidence returns 409. No vectors or scores are returned to workers."
            }
        },
        "/api/v1/mobile/face/enrollments/{enrollment}/timeline": {
            "get": {
                "summary": "Enrollment Timeline (Face Workflow)",
                "tags": [
                    "Attendance"
                ],
                "operationId": "faceWorkflowEnrollmentTimeline",
                "parameters": [
                    {
                        "name": "enrollment",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Server-owned biometric workflow state",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": [
                                                {
                                                    "id": "00000000-0000-4000-8000-000000000001",
                                                    "action": "attendance.rejected",
                                                    "reason": "Reviewer explanation",
                                                    "at": "2026-11-17T16:10:00Z"
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Permission, consent withdrawal or disabled fallback policy."
                    },
                    "409": {
                        "description": "Expired session, conflicting evidence or stale review."
                    },
                    "422": {
                        "description": "Invalid movement report, consent or image list."
                    },
                    "429": {
                        "description": "Rate limited."
                    }
                },
                "x-generated": true,
                "description": " Contract version 2 is additive to v1. Server-issued sessions precede the movement check. Automatic enrollment and attendance acceptance are disabled. Processing captures are polled through the existing owned capture endpoint. Identical evidence retries preserve bytes/report; different evidence returns 409. No vectors or scores are returned to workers."
            }
        },
        "/api/v1/mobile/face/fallback": {
            "post": {
                "summary": "Fallback (Face Workflow)",
                "tags": [
                    "Attendance"
                ],
                "operationId": "faceWorkflowFallback",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "action": {
                                        "type": "string",
                                        "enum": [
                                            "clock_in",
                                            "clock_out"
                                        ]
                                    },
                                    "reason": {
                                        "type": "string",
                                        "description": "max: 1000"
                                    }
                                },
                                "required": [
                                    "action",
                                    "reason"
                                ]
                            },
                            "example": {
                                "action": "clock_in",
                                "reason": "Camera unavailable; request independent attendance review."
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Server-owned biometric workflow state",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "00000000-0000-4000-8000-000000000001",
                                                "action": "clock_in",
                                                "status": "issued",
                                                "contract_version": 2,
                                                "challenges": [
                                                    "blink",
                                                    "look_up",
                                                    "turn_left"
                                                ],
                                                "nonce": "SERVER_ISSUED_NONCE",
                                                "liveness_assurance": "device_reported",
                                                "expires_at": "2026-11-17T08:05:00Z"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Permission, consent withdrawal or disabled fallback policy."
                    },
                    "409": {
                        "description": "Expired session, conflicting evidence or stale review."
                    },
                    "422": {
                        "description": "Invalid movement report, consent or image list."
                    },
                    "429": {
                        "description": "Rate limited."
                    }
                },
                "x-generated": true,
                "description": " Contract version 2 is additive to v1. Server-issued sessions precede the movement check. Automatic enrollment and attendance acceptance are disabled. Processing captures are polled through the existing owned capture endpoint. Identical evidence retries preserve bytes/report; different evidence returns 409. No vectors or scores are returned to workers."
            }
        },
        "/api/v1/mobile/face/policy": {
            "get": {
                "summary": "Policy (Face Workflow)",
                "tags": [
                    "Attendance"
                ],
                "operationId": "faceWorkflowPolicy",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Server-owned biometric workflow state",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "contractVersion": 2,
                                                "noticeVersion": "face-v1",
                                                "notice": "Employer biometric attendance notice.",
                                                "consentId": null,
                                                "reviewOnly": true,
                                                "automaticEnrollmentEnabled": false,
                                                "automaticClockVerificationEnabled": false,
                                                "livenessAssurance": "device_reported",
                                                "fallbackAllowed": false
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Permission, consent withdrawal or disabled fallback policy."
                    },
                    "409": {
                        "description": "Expired session, conflicting evidence or stale review."
                    },
                    "422": {
                        "description": "Invalid movement report, consent or image list."
                    },
                    "429": {
                        "description": "Rate limited."
                    }
                },
                "x-generated": true,
                "description": " Contract version 2 is additive to v1. Server-issued sessions precede the movement check. Automatic enrollment and attendance acceptance are disabled. Processing captures are polled through the existing owned capture endpoint. Identical evidence retries preserve bytes/report; different evidence returns 409. No vectors or scores are returned to workers."
            }
        },
        "/api/v1/mobile/incidents": {
            "get": {
                "summary": "List your incident reports",
                "tags": [
                    "Incidents"
                ],
                "operationId": "myIncidentIndex",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Incident reference, type, severity, description and current status.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": [
                                                {
                                                    "id": "9",
                                                    "reference": "INC-01KWORKERREPORT000000000000",
                                                    "type": "Others",
                                                    "severity": "Critical",
                                                    "description": "A power cable fell across the entrance.",
                                                    "status": "Open",
                                                    "clientRef": "offline-incident-1",
                                                    "alreadyReceived": false
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired bearer token."
                    },
                    "403": {
                        "description": "The worker account is inactive or must complete password setup."
                    },
                    "404": {
                        "description": "The requested record does not belong to this worker."
                    },
                    "422": {
                        "description": "Invalid type or severity, missing description or photos, invalid occurrence date, or an unassigned project."
                    }
                },
                "description": "Return the incidents you reported, including reference, type, severity, description, status and photo count.",
                "x-generated": true
            },
            "post": {
                "summary": "Submit an incident report",
                "tags": [
                    "Incidents"
                ],
                "operationId": "myIncidentStore",
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "clientRef": {
                                        "type": "string",
                                        "description": "max: 64"
                                    },
                                    "description": {
                                        "type": "string",
                                        "description": "max: 5000"
                                    },
                                    "deviceSubmittedAt": {
                                        "type": "string",
                                        "nullable": true,
                                        "format": "date"
                                    },
                                    "latitude": {
                                        "type": "number",
                                        "nullable": true,
                                        "description": "required with longitude"
                                    },
                                    "location": {
                                        "type": "string",
                                        "nullable": true,
                                        "description": "max: 500"
                                    },
                                    "longitude": {
                                        "type": "number",
                                        "nullable": true,
                                        "description": "required with latitude"
                                    },
                                    "occurredAt": {
                                        "type": "string",
                                        "format": "date"
                                    },
                                    "peopleInvolved": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "employeeId": {
                                                    "type": "integer",
                                                    "nullable": true
                                                },
                                                "injury": {
                                                    "type": "string",
                                                    "nullable": true,
                                                    "description": "max: 500"
                                                },
                                                "name": {
                                                    "type": "string",
                                                    "description": "max: 255"
                                                },
                                                "role": {
                                                    "type": "string",
                                                    "enum": [
                                                        "injured",
                                                        "witness",
                                                        "involved"
                                                    ]
                                                }
                                            },
                                            "required": [
                                                "name",
                                                "role"
                                            ]
                                        },
                                        "nullable": true,
                                        "description": "max: 30"
                                    },
                                    "photos": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "format": "binary",
                                            "description": "max: 2048"
                                        },
                                        "description": "min: 1; max: 10"
                                    },
                                    "projectId": {
                                        "type": "integer",
                                        "nullable": true
                                    },
                                    "severity": {
                                        "type": "string",
                                        "enum": [
                                            "Low",
                                            "Medium",
                                            "High",
                                            "Critical"
                                        ]
                                    },
                                    "site": {
                                        "type": "string",
                                        "nullable": true,
                                        "description": "required without projectId; max: 255"
                                    },
                                    "type": {
                                        "type": "string",
                                        "enum": [
                                            "Near miss",
                                            "Injury",
                                            "Property damage",
                                            "Unsafe condition",
                                            "Unsafe act",
                                            "Environmental",
                                            "Vehicle",
                                            "Fire",
                                            "Other",
                                            "Others"
                                        ]
                                    },
                                    "urgency": {
                                        "type": "string",
                                        "enum": [
                                            "routine",
                                            "urgent",
                                            "emergency"
                                        ]
                                    }
                                },
                                "required": [
                                    "clientRef",
                                    "description",
                                    "occurredAt",
                                    "photos",
                                    "severity",
                                    "type"
                                ]
                            },
                            "example": {
                                "clientRef": "offline-incident-1",
                                "type": "Others",
                                "severity": "Critical",
                                "projectId": 2,
                                "occurredAt": "2026-11-04T10:00:00+01:00",
                                "description": "Fallen power cable",
                                "photos": [
                                    "(binary image)"
                                ]
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Incident reference, type, severity, description and current status.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "9",
                                                "reference": "INC-01KWORKERREPORT000000000000",
                                                "type": "Others",
                                                "severity": "Critical",
                                                "description": "A power cable fell across the entrance.",
                                                "status": "Open",
                                                "clientRef": "offline-incident-1",
                                                "alreadyReceived": false
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired bearer token."
                    },
                    "403": {
                        "description": "The worker account is inactive or must complete password setup."
                    },
                    "404": {
                        "description": "The requested record does not belong to this worker."
                    },
                    "422": {
                        "description": "Invalid type or severity, missing description or photos, invalid occurrence date, or an unassigned project."
                    },
                    "503": {
                        "description": "Malware scanning or private storage is unavailable; submission failed. Keep the draft and retry after service recovery.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "scannerUnavailable": {
                                        "value": {
                                            "message": "Document scanning is temporarily unavailable. Your file was not saved. Please try again later."
                                        }
                                    },
                                    "storageUnavailable": {
                                        "value": {
                                            "message": "Cloudinary storage is temporarily unavailable. Please try again later."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "200": {
                        "description": "The report already submitted with this clientRef.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "existing": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "9",
                                                "reference": "INC-01KWORKERREPORT000000000000",
                                                "type": "Others",
                                                "severity": "Critical",
                                                "description": "A power cable fell across the entrance.",
                                                "status": "Open",
                                                "clientRef": "offline-incident-1",
                                                "alreadyReceived": true
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "The clientRef was used by another account."
                    }
                },
                "description": "Send clientRef, type, severity, occurredAt, description, projectId or site, and at least one photos[] image as multipart form-data. Severity accepts Low, Medium, High or Critical. Returns the incident reference, type and severity. Reusing your clientRef returns the original report.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/incidents/form": {
            "get": {
                "summary": "Get incident form options",
                "tags": [
                    "Incidents"
                ],
                "operationId": "myIncidentForm",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Incident types, severities, urgency options, projects and crewmates.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "types": [
                                                    "Near miss",
                                                    "Injury",
                                                    "Property damage",
                                                    "Unsafe condition",
                                                    "Unsafe act",
                                                    "Environmental",
                                                    "Vehicle",
                                                    "Fire",
                                                    "Other",
                                                    "Others"
                                                ],
                                                "severities": [
                                                    "Low",
                                                    "Medium",
                                                    "High",
                                                    "Critical"
                                                ],
                                                "projects": [
                                                    {
                                                        "id": 2,
                                                        "name": "Assigned site"
                                                    }
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired bearer token."
                    },
                    "403": {
                        "description": "The worker account is inactive or must complete password setup."
                    },
                    "404": {
                        "description": "The requested record does not belong to this worker."
                    },
                    "422": {
                        "description": "Invalid type or severity, missing description or photos, invalid occurrence date, or an unassigned project."
                    }
                },
                "description": "Return incident types, severity levels, urgency options, assigned projects and crewmates for the report form.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/incidents/{incident}": {
            "get": {
                "summary": "Get your incident report",
                "tags": [
                    "Incidents"
                ],
                "operationId": "myIncidentShow",
                "parameters": [
                    {
                        "name": "incident",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Incident reference, type, severity, description and current status.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "9",
                                                "reference": "INC-01KWORKERREPORT000000000000",
                                                "type": "Others",
                                                "severity": "Critical",
                                                "description": "A power cable fell across the entrance.",
                                                "status": "Open",
                                                "clientRef": "offline-incident-1",
                                                "alreadyReceived": false
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired bearer token."
                    },
                    "403": {
                        "description": "The worker account is inactive or must complete password setup."
                    },
                    "404": {
                        "description": "The requested record does not belong to this worker."
                    },
                    "422": {
                        "description": "Invalid type or severity, missing description or photos, invalid occurrence date, or an unassigned project."
                    }
                },
                "description": "Return the selected report’s reference, description, severity, status, project and photo download URLs. Use the incident ID returned on submission.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/incidents/{safetyIncident}/photos": {
            "post": {
                "summary": "Add photos to your incident",
                "tags": [
                    "Incidents"
                ],
                "operationId": "safetyIncidentAddPhotos",
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "photos": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "format": "binary",
                                            "description": "max: 2048"
                                        },
                                        "description": "min: 1; max: 10"
                                    }
                                },
                                "required": [
                                    "photos"
                                ]
                            },
                            "example": {
                                "photos": [
                                    "(binary image)"
                                ]
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "safetyIncident",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Incident reference, type, severity and updated photo count.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "9",
                                                "reference": "INC-01KWORKERREPORT000000000000",
                                                "type": "Others",
                                                "severity": "Critical",
                                                "description": "A power cable fell across the entrance.",
                                                "status": "Open",
                                                "clientRef": "offline-incident-1",
                                                "alreadyReceived": false
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired bearer token."
                    },
                    "403": {
                        "description": "The worker account is inactive or must complete password setup."
                    },
                    "404": {
                        "description": "The requested record does not belong to this worker."
                    },
                    "422": {
                        "description": "Invalid type or severity, missing description or photos, invalid occurrence date, or an unassigned project."
                    },
                    "503": {
                        "description": "Malware scanning or private storage is unavailable; submission failed. Keep the draft and retry after service recovery.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "scannerUnavailable": {
                                        "value": {
                                            "message": "Document scanning is temporarily unavailable. Your file was not saved. Please try again later."
                                        }
                                    },
                                    "storageUnavailable": {
                                        "value": {
                                            "message": "Cloudinary storage is temporarily unavailable. Please try again later."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "The incident is closed and cannot receive more photos."
                    }
                },
                "description": "Send one to ten photos[] images as multipart form-data. Photos can be added only to a report you submitted that is still open or investigating.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/incidents/{safetyIncident}/photos/{photo}": {
            "get": {
                "summary": "Download an incident photo",
                "tags": [
                    "Incidents"
                ],
                "operationId": "safetyIncidentPhoto",
                "parameters": [
                    {
                        "name": "safetyIncident",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "photo",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Return a photo belonging to the selected incident you reported. Both the report and photo IDs must match.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Authentication required."
                    },
                    "403": {
                        "description": "Worker account is not eligible."
                    },
                    "404": {
                        "description": "File not found or owned by another employee."
                    }
                },
                "description": "Return a photo belonging to the selected incident you reported. Both the report and photo IDs must match.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/leave-balances": {
            "get": {
                "summary": "Get your leave balances",
                "tags": [
                    "Leave"
                ],
                "operationId": "mobileLeaveBalances",
                "parameters": [
                    {
                        "name": "year",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "description": "min: 2000; max: 2100"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Return the leave types available to you, supportingDocumentsRequired for each type and each allowance’s approved usage, pending reservations and available days. Use year for the start year of the leave period.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "balances": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "year": 2027,
                                                "dayBasis": "calendar",
                                                "yearStartsMonth": 1,
                                                "reservePending": true,
                                                "allowances": [
                                                    {
                                                        "leaveType": "Annual",
                                                        "supportingDocumentsRequired": false,
                                                        "allowanceDays": 20,
                                                        "approvedDays": 0,
                                                        "pendingDays": 3,
                                                        "remainingDays": 20,
                                                        "availableDays": 17,
                                                        "year": 2027,
                                                        "periodStart": "2027-01-01",
                                                        "periodEnd": "2027-12-31"
                                                    }
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid credentials or expired bearer token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    },
                                    "setupRequired": {
                                        "value": {
                                            "status": "error",
                                            "code": "password_change_required",
                                            "message": "Replace your temporary password to continue."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "perPage": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Return the leave types available to you, supportingDocumentsRequired for each type and each allowance’s approved usage, pending reservations and available days. Use year for the start year of the leave period.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/leave-requests": {
            "get": {
                "summary": "List your leave requests",
                "tags": [
                    "Leave"
                ],
                "operationId": "mobileLeaveIndex",
                "parameters": [
                    {
                        "name": "perPage",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "description": "min: 1; max: 100"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "Pending",
                                "InReview",
                                "Approved",
                                "Rejected",
                                "Cancelled"
                            ]
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Return your leave requests, including Cancelled records, and dated progress. id and uuid are the public UUID. canCancel indicates whether you can cancel your own pending or in-review request. Filter by status, including Cancelled, and use perPage to set the page size.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "request": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "current_page": 1,
                                                "data": [
                                                    {
                                                        "id": "b14db530-179d-48c7-94f4-ea58b66e4201",
                                                        "uuid": "b14db530-179d-48c7-94f4-ea58b66e4201",
                                                        "employeeId": 3,
                                                        "isOwnRequest": true,
                                                        "canCancel": true,
                                                        "chargeableDays": 3,
                                                        "dayBasis": "calendar",
                                                        "submittedAt": "2027-07-01T09:00:00+00:00",
                                                        "decidedBy": null,
                                                        "decidedAt": null,
                                                        "decisionReason": null,
                                                        "supportingDocumentsRequired": false,
                                                        "supportingDocuments": [],
                                                        "progress": [
                                                            {
                                                                "stage": "sent",
                                                                "date": "2027-07-01T09:00:00+00:00",
                                                                "actorId": 12,
                                                                "actorName": "Ada Worker",
                                                                "reason": "Family commitments"
                                                            }
                                                        ],
                                                        "code": "LR-01K00000000000000000000000",
                                                        "employeeName": "Ada Worker",
                                                        "employeeInitials": "AW",
                                                        "avatarColor": "#2563EB",
                                                        "role": "Worker",
                                                        "project": null,
                                                        "leaveType": "Annual",
                                                        "startDate": "2027-08-02",
                                                        "endDate": "2027-08-04",
                                                        "duration": "3d",
                                                        "status": "Pending",
                                                        "reason": "Family commitments",
                                                        "reviewerName": null,
                                                        "rejectionReason": null
                                                    }
                                                ],
                                                "first_page_url": "/api/v1/mobile/leave-requests?page=1",
                                                "from": 1,
                                                "last_page": 1,
                                                "last_page_url": "/api/v1/mobile/leave-requests?page=1",
                                                "links": [
                                                    {
                                                        "url": null,
                                                        "label": "&laquo; Previous",
                                                        "active": false
                                                    },
                                                    {
                                                        "url": "/api/v1/mobile/leave-requests?page=1",
                                                        "label": "1",
                                                        "active": true
                                                    },
                                                    {
                                                        "url": null,
                                                        "label": "Next &raquo;",
                                                        "active": false
                                                    }
                                                ],
                                                "next_page_url": null,
                                                "path": "/api/v1/mobile/leave-requests",
                                                "per_page": 25,
                                                "prev_page_url": null,
                                                "to": 1,
                                                "total": 1
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid credentials or expired bearer token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    },
                                    "setupRequired": {
                                        "value": {
                                            "status": "error",
                                            "code": "password_change_required",
                                            "message": "Replace your temporary password to continue."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "perPage": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Return your leave requests, including Cancelled records, and dated progress. id and uuid are the public UUID. canCancel indicates whether you can cancel your own pending or in-review request. Filter by status, including Cancelled, and use perPage to set the page size.",
                "x-generated": true
            },
            "post": {
                "summary": "Submit a leave request",
                "tags": [
                    "Leave"
                ],
                "operationId": "mobileLeaveStore",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "endDate": {
                                        "type": "string",
                                        "format": "date"
                                    },
                                    "leaveType": {
                                        "type": "string",
                                        "description": "max: 20"
                                    },
                                    "reason": {
                                        "type": "string",
                                        "description": "max: 2000"
                                    },
                                    "startDate": {
                                        "type": "string",
                                        "format": "date"
                                    },
                                    "supportingDocumentIds": {
                                        "type": "array",
                                        "items": {
                                            "type": "integer",
                                            "description": "min: 1"
                                        },
                                        "description": "max: 10"
                                    }
                                },
                                "required": [
                                    "endDate",
                                    "leaveType",
                                    "reason",
                                    "startDate"
                                ]
                            },
                            "example": {
                                "leaveType": "Annual",
                                "startDate": "2027-08-02",
                                "endDate": "2027-08-04",
                                "reason": "Family commitments",
                                "supportingDocumentIds": []
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "maxLength": 150
                        },
                        "description": "Client-generated key persisted with the offline request. Reuse with identical details returns the original request; different details return 409."
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Idempotent replay returns the original request.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "request": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "b14db530-179d-48c7-94f4-ea58b66e4201",
                                                "uuid": "b14db530-179d-48c7-94f4-ea58b66e4201",
                                                "employeeId": 3,
                                                "isOwnRequest": true,
                                                "canCancel": true,
                                                "chargeableDays": 3,
                                                "dayBasis": "calendar",
                                                "submittedAt": "2027-07-01T09:00:00+00:00",
                                                "decidedBy": null,
                                                "decidedAt": null,
                                                "decisionReason": null,
                                                "supportingDocumentsRequired": false,
                                                "supportingDocuments": [],
                                                "progress": [
                                                    {
                                                        "stage": "sent",
                                                        "date": "2027-07-01T09:00:00+00:00",
                                                        "actorId": 12,
                                                        "actorName": "Ada Worker",
                                                        "reason": "Family commitments"
                                                    }
                                                ],
                                                "code": "LR-01K00000000000000000000000",
                                                "employeeName": "Ada Worker",
                                                "employeeInitials": "AW",
                                                "avatarColor": "#2563EB",
                                                "role": "Worker",
                                                "project": null,
                                                "leaveType": "Annual",
                                                "startDate": "2027-08-02",
                                                "endDate": "2027-08-04",
                                                "duration": "3d",
                                                "status": "Pending",
                                                "reason": "Family commitments",
                                                "reviewerName": null,
                                                "rejectionReason": null
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "201": {
                        "description": "New leave request created.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "request": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "b14db530-179d-48c7-94f4-ea58b66e4201",
                                                "uuid": "b14db530-179d-48c7-94f4-ea58b66e4201",
                                                "employeeId": 3,
                                                "isOwnRequest": true,
                                                "canCancel": true,
                                                "chargeableDays": 3,
                                                "dayBasis": "calendar",
                                                "submittedAt": "2027-07-01T09:00:00+00:00",
                                                "decidedBy": null,
                                                "decidedAt": null,
                                                "decisionReason": null,
                                                "supportingDocumentsRequired": false,
                                                "supportingDocuments": [],
                                                "progress": [
                                                    {
                                                        "stage": "sent",
                                                        "date": "2027-07-01T09:00:00+00:00",
                                                        "actorId": 12,
                                                        "actorName": "Ada Worker",
                                                        "reason": "Family commitments"
                                                    }
                                                ],
                                                "code": "LR-01K00000000000000000000000",
                                                "employeeName": "Ada Worker",
                                                "employeeInitials": "AW",
                                                "avatarColor": "#2563EB",
                                                "role": "Worker",
                                                "project": null,
                                                "leaveType": "Annual",
                                                "startDate": "2027-08-02",
                                                "endDate": "2027-08-04",
                                                "duration": "3d",
                                                "status": "Pending",
                                                "reason": "Family commitments",
                                                "reviewerName": null,
                                                "rejectionReason": null
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid credentials or expired bearer token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    },
                                    "setupRequired": {
                                        "value": {
                                            "status": "error",
                                            "code": "password_change_required",
                                            "message": "Replace your temporary password to continue."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "leaveType": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "Registration conflict/device limit, or idempotency key reused with different leave details.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "conflict": {
                                        "value": {
                                            "message": "This idempotency key has already been used with different leave details."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Send leaveType, startDate, endDate and reason, with a stable Idempotency-Key header. Read supportingDocumentsRequired for the chosen type from leave-balances. Upload PDF or image files to POST /mobile/documents with category=Supporting, then send up to 10 returned IDs as supportingDocumentIds. Each document must belong to your employee. At least one is required when the policy toggle is on; documents are optional when off. Reordering IDs is an identical retry. Returns the saved request and its UUID. An identical retry returns the same request; changing the payload with the same key returns 409.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/leave-requests/{leaveId}": {
            "get": {
                "summary": "Get your leave request",
                "tags": [
                    "Leave"
                ],
                "operationId": "mobileLeaveShow",
                "parameters": [
                    {
                        "name": "leaveId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Use the UUID returned on submission. Returns the request details, decision, reviewer, dated progress, the supportingDocumentsRequired value recorded at submission and linked supportingDocuments with private download URLs.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "pending": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "b14db530-179d-48c7-94f4-ea58b66e4201",
                                                "uuid": "b14db530-179d-48c7-94f4-ea58b66e4201",
                                                "employeeId": 3,
                                                "isOwnRequest": true,
                                                "canCancel": true,
                                                "chargeableDays": 3,
                                                "dayBasis": "calendar",
                                                "submittedAt": "2027-07-01T09:00:00+00:00",
                                                "decidedBy": null,
                                                "decidedAt": null,
                                                "decisionReason": null,
                                                "supportingDocumentsRequired": false,
                                                "supportingDocuments": [],
                                                "progress": [
                                                    {
                                                        "stage": "sent",
                                                        "date": "2027-07-01T09:00:00+00:00",
                                                        "actorId": 12,
                                                        "actorName": "Ada Worker",
                                                        "reason": "Family commitments"
                                                    }
                                                ],
                                                "code": "LR-01K00000000000000000000000",
                                                "employeeName": "Ada Worker",
                                                "employeeInitials": "AW",
                                                "avatarColor": "#2563EB",
                                                "role": "Worker",
                                                "project": null,
                                                "leaveType": "Annual",
                                                "startDate": "2027-08-02",
                                                "endDate": "2027-08-04",
                                                "duration": "3d",
                                                "status": "Pending",
                                                "reason": "Family commitments",
                                                "reviewerName": null,
                                                "rejectionReason": null
                                            }
                                        }
                                    },
                                    "approved": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "b14db530-179d-48c7-94f4-ea58b66e4201",
                                                "uuid": "b14db530-179d-48c7-94f4-ea58b66e4201",
                                                "employeeId": 3,
                                                "isOwnRequest": true,
                                                "canCancel": false,
                                                "chargeableDays": 3,
                                                "dayBasis": "calendar",
                                                "submittedAt": "2027-07-01T09:00:00+00:00",
                                                "decidedBy": 18,
                                                "decidedAt": "2027-07-01T10:00:00+00:00",
                                                "decisionReason": "Staffing cover arranged",
                                                "supportingDocumentsRequired": false,
                                                "supportingDocuments": [],
                                                "progress": [
                                                    {
                                                        "stage": "sent",
                                                        "date": "2027-07-01T09:00:00+00:00",
                                                        "actorId": 12,
                                                        "actorName": "Ada Worker",
                                                        "reason": "Family commitments"
                                                    },
                                                    {
                                                        "stage": "in_progress",
                                                        "date": "2027-07-01T09:15:00+00:00",
                                                        "actorId": 18,
                                                        "actorName": "Chris Manager",
                                                        "reason": "Checking staffing"
                                                    },
                                                    {
                                                        "stage": "approved",
                                                        "date": "2027-07-01T10:00:00+00:00",
                                                        "actorId": 18,
                                                        "actorName": "Chris Manager",
                                                        "reason": "Staffing cover arranged"
                                                    }
                                                ],
                                                "code": "LR-01K00000000000000000000000",
                                                "employeeName": "Ada Worker",
                                                "employeeInitials": "AW",
                                                "avatarColor": "#2563EB",
                                                "role": "Worker",
                                                "project": null,
                                                "leaveType": "Annual",
                                                "startDate": "2027-08-02",
                                                "endDate": "2027-08-04",
                                                "duration": "3d",
                                                "status": "Approved",
                                                "reason": "Family commitments",
                                                "reviewerName": "Chris Manager",
                                                "rejectionReason": null
                                            }
                                        }
                                    },
                                    "rejected": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "b14db530-179d-48c7-94f4-ea58b66e4201",
                                                "uuid": "b14db530-179d-48c7-94f4-ea58b66e4201",
                                                "employeeId": 3,
                                                "isOwnRequest": true,
                                                "canCancel": false,
                                                "chargeableDays": 3,
                                                "dayBasis": "calendar",
                                                "submittedAt": "2027-07-01T09:00:00+00:00",
                                                "decidedBy": 18,
                                                "decidedAt": "2027-07-01T10:00:00+00:00",
                                                "decisionReason": "Please correct the requested dates",
                                                "supportingDocumentsRequired": false,
                                                "supportingDocuments": [],
                                                "progress": [
                                                    {
                                                        "stage": "sent",
                                                        "date": "2027-07-01T09:00:00+00:00",
                                                        "actorId": 12,
                                                        "actorName": "Ada Worker",
                                                        "reason": "Family commitments"
                                                    },
                                                    {
                                                        "stage": "in_progress",
                                                        "date": "2027-07-01T09:15:00+00:00",
                                                        "actorId": 18,
                                                        "actorName": "Chris Manager",
                                                        "reason": "Checking staffing"
                                                    },
                                                    {
                                                        "stage": "rejected",
                                                        "date": "2027-07-01T10:00:00+00:00",
                                                        "actorId": 18,
                                                        "actorName": "Chris Manager",
                                                        "reason": "Please correct the requested dates"
                                                    }
                                                ],
                                                "code": "LR-01K00000000000000000000000",
                                                "employeeName": "Ada Worker",
                                                "employeeInitials": "AW",
                                                "avatarColor": "#2563EB",
                                                "role": "Worker",
                                                "project": null,
                                                "leaveType": "Annual",
                                                "startDate": "2027-08-02",
                                                "endDate": "2027-08-04",
                                                "duration": "3d",
                                                "status": "Rejected",
                                                "reason": "Family commitments",
                                                "reviewerName": "Chris Manager",
                                                "rejectionReason": "Please correct the requested dates"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid credentials or expired bearer token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    },
                                    "setupRequired": {
                                        "value": {
                                            "status": "error",
                                            "code": "password_change_required",
                                            "message": "Replace your temporary password to continue."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "perPage": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Use the UUID returned on submission. Returns the request details, decision, reviewer, dated progress, the supportingDocumentsRequired value recorded at submission and linked supportingDocuments with private download URLs.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/leave-requests/{leaveId}/cancel": {
            "post": {
                "summary": "Cancel your leave request",
                "tags": [
                    "Leave"
                ],
                "operationId": "mobileLeaveCancel",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "reason": {
                                        "type": "string",
                                        "nullable": true,
                                        "description": "max: 2000"
                                    }
                                }
                            },
                            "example": {
                                "reason": "Plans changed"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "leaveId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Use the request UUID and optionally send reason. Cancels your pending or in-review request and releases reserved days. Retains the record, UUID, attachments and progress for worker and tenant history. Repeating cancellation returns the existing result and preserves the original cancellation reason and date. Approved or rejected requests return 422. canCancel is false after cancellation.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "cancelled": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "b14db530-179d-48c7-94f4-ea58b66e4201",
                                                "uuid": "b14db530-179d-48c7-94f4-ea58b66e4201",
                                                "employeeId": 3,
                                                "isOwnRequest": true,
                                                "canCancel": false,
                                                "chargeableDays": 3,
                                                "dayBasis": "calendar",
                                                "submittedAt": "2027-07-01T09:00:00+00:00",
                                                "decidedBy": null,
                                                "decidedAt": null,
                                                "decisionReason": null,
                                                "supportingDocumentsRequired": false,
                                                "supportingDocuments": [],
                                                "progress": [
                                                    {
                                                        "stage": "sent",
                                                        "date": "2027-07-01T09:00:00+00:00",
                                                        "actorId": 12,
                                                        "actorName": "Ada Worker",
                                                        "reason": "Family commitments"
                                                    },
                                                    {
                                                        "stage": "cancelled",
                                                        "date": "2027-07-01T10:00:00+00:00",
                                                        "actorId": 12,
                                                        "actorName": "Ada Worker",
                                                        "reason": "Plans changed"
                                                    }
                                                ],
                                                "code": "LR-01K00000000000000000000000",
                                                "employeeName": "Ada Worker",
                                                "employeeInitials": "AW",
                                                "avatarColor": "#2563EB",
                                                "role": "Worker",
                                                "project": null,
                                                "leaveType": "Annual",
                                                "startDate": "2027-08-02",
                                                "endDate": "2027-08-04",
                                                "duration": "3d",
                                                "status": "Cancelled",
                                                "reason": "Family commitments",
                                                "reviewerName": null,
                                                "rejectionReason": null
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid credentials or expired bearer token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    },
                                    "setupRequired": {
                                        "value": {
                                            "status": "error",
                                            "code": "password_change_required",
                                            "message": "Replace your temporary password to continue."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "reason": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Use the request UUID and optionally send reason. Cancels your pending or in-review request and releases reserved days. Retains the record, UUID, attachments and progress for worker and tenant history. Repeating cancellation returns the existing result and preserves the original cancellation reason and date. Approved or rejected requests return 422. canCancel is false after cancellation.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/leave-requests/{leaveId}/supporting-documents/{document}/download": {
            "get": {
                "summary": "Download your leave supporting document",
                "tags": [
                    "Leave"
                ],
                "operationId": "mobileLeaveDownloadSupportingDocument",
                "parameters": [
                    {
                        "name": "leaveId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "document",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Private supporting file. Cache-Control is private, no-store.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid credentials or expired bearer token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    },
                                    "setupRequired": {
                                        "value": {
                                            "status": "error",
                                            "code": "password_change_required",
                                            "message": "Replace your temporary password to continue."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "perPage": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Use your leave UUID and a supportingDocuments id returned on that request. Downloads the private file only when both the request and linked document belong to your employee. Unlinked, foreign-worker and foreign-tenant files return 404.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/me": {
            "get": {
                "summary": "Get your worker profile",
                "tags": [
                    "Profile"
                ],
                "operationId": "mobileProfileMe",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Return your account, employee record, emergency contact, company, assigned site and current or next scheduled shift. role is the access role (for example field-worker); employee.jobTitle is the employee position or trade. tenant.country and tenant.currency are the configured company values. employee.phone is the personal contact number. employment, identity and payment are read-only worker views; completeness lists missing fields and identifies which sections staff manage. Use completeness.onboarding.profileIncomplete for an informational marker. Identity verification reflects reviewed evidence, not merely a saved ID number. Sensitive profile responses use private/no-store caching. Keep phone and emergency contact updates on their separate endpoints.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "profile": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "employee_id": 3,
                                                "user": {
                                                    "id": 12,
                                                    "name": "Ada Worker",
                                                    "email": "worker@example.test",
                                                    "username": "worker.notifications",
                                                    "must_change_password": false
                                                },
                                                "tenant": {
                                                    "uuid": "c14db530-179d-48c7-94f4-ea58b66e4201",
                                                    "name": "Demo Tenant",
                                                    "timezone": "Africa/Lagos",
                                                    "country": "NG",
                                                    "currency": "NGN"
                                                },
                                                "role": "field-worker",
                                                "can_view_shifts": true,
                                                "employee": {
                                                    "id": 3,
                                                    "employee_no": "EMP-003",
                                                    "jobTitle": "Scaffolder",
                                                    "name": "Ada Worker",
                                                    "email": "worker@example.test",
                                                    "phone": "+2348000000000",
                                                    "status": "active",
                                                    "project_id": null,
                                                    "crew_id": null,
                                                    "emergencyContact": {
                                                        "fullName": "Bola Ahmed",
                                                        "relationship": "Sibling",
                                                        "phone": "+2348012345679"
                                                    }
                                                },
                                                "employment": {
                                                    "readOnly": true,
                                                    "jobTitle": "Scaffolder",
                                                    "employmentType": "full_time",
                                                    "department": "Site operations",
                                                    "startDate": "2026-11-01",
                                                    "status": "active",
                                                    "lifecycleStage": "active",
                                                    "supervisor": null,
                                                    "crew": null,
                                                    "pay": {
                                                        "rate": "250000.00",
                                                        "currency": "NGN",
                                                        "unit": "monthly",
                                                        "effectiveFrom": "2026-11-01"
                                                    }
                                                },
                                                "identity": {
                                                    "readOnly": true,
                                                    "image": null,
                                                    "country": "NG",
                                                    "documentType": null,
                                                    "documentNumber": null,
                                                    "dateOfBirth": null,
                                                    "nationalId": null,
                                                    "bankVerificationNumber": null,
                                                    "residentialAddress": null,
                                                    "verification": {
                                                        "status": "missing",
                                                        "items": [
                                                            {
                                                                "key": "national_id",
                                                                "label": "National ID (NIN slip or card)",
                                                                "status": "missing",
                                                                "documentId": null
                                                            },
                                                            {
                                                                "key": "proof_of_address",
                                                                "label": "Proof of address",
                                                                "status": "missing",
                                                                "documentId": null
                                                            }
                                                        ]
                                                    }
                                                },
                                                "payment": {
                                                    "readOnly": true,
                                                    "country": "NG",
                                                    "branchCode": null,
                                                    "bankCode": null,
                                                    "bankName": null,
                                                    "accountName": null,
                                                    "accountNumber": null,
                                                    "taxId": null,
                                                    "taxState": null,
                                                    "pensionProvider": null,
                                                    "pensionPin": null,
                                                    "housingFundNumber": null,
                                                    "updatedAt": null
                                                },
                                                "completeness": {
                                                    "isComplete": false,
                                                    "missing": [
                                                        "identity.dateOfBirth",
                                                        "identity.documentNumber",
                                                        "identity.residentialAddress",
                                                        "identity.imageDocumentId",
                                                        "payment.bankName",
                                                        "payment.accountName",
                                                        "payment.accountNumber",
                                                        "payment.bankCode"
                                                    ],
                                                    "workerMissing": [],
                                                    "sections": {
                                                        "employment": {
                                                            "complete": true,
                                                            "missing": [],
                                                            "managedBy": "tenant_admin"
                                                        },
                                                        "company": {
                                                            "complete": true,
                                                            "missing": [],
                                                            "managedBy": "tenant_admin"
                                                        },
                                                        "contact": {
                                                            "complete": true,
                                                            "missing": [],
                                                            "managedBy": "worker"
                                                        },
                                                        "identity": {
                                                            "complete": false,
                                                            "missing": [
                                                                "identity.dateOfBirth",
                                                                "identity.documentNumber",
                                                                "identity.residentialAddress",
                                                                "identity.imageDocumentId"
                                                            ],
                                                            "managedBy": "tenant_admin"
                                                        },
                                                        "payment": {
                                                            "complete": false,
                                                            "missing": [
                                                                "payment.bankName",
                                                                "payment.accountName",
                                                                "payment.accountNumber",
                                                                "payment.bankCode"
                                                            ],
                                                            "managedBy": "tenant_admin"
                                                        }
                                                    },
                                                    "onboarding": {
                                                        "enforced": false,
                                                        "enforcement": "none",
                                                        "managedBy": "tenant_admin",
                                                        "requiresSetup": false,
                                                        "setupComplete": false,
                                                        "profileIncomplete": true,
                                                        "nextStep": "identity_image",
                                                        "canUploadIdentityImage": true,
                                                        "canSubmit": true,
                                                        "status": "incomplete",
                                                        "submittedAt": null
                                                    }
                                                },
                                                "assigned_site": null,
                                                "current_shift": null,
                                                "next_shift": null
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid credentials or expired bearer token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    },
                                    "setupRequired": {
                                        "value": {
                                            "status": "error",
                                            "code": "password_change_required",
                                            "message": "Replace your temporary password to continue."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "perPage": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Return your account, employee record, emergency contact, company, assigned site and current or next scheduled shift. role is the access role (for example field-worker); employee.jobTitle is the employee position or trade. tenant.country and tenant.currency are the configured company values. employee.phone is the personal contact number. employment, identity and payment are read-only worker views; completeness lists missing fields and identifies which sections staff manage. Use completeness.onboarding.profileIncomplete for an informational marker. Identity verification reflects reviewed evidence, not merely a saved ID number. Sensitive profile responses use private/no-store caching. Keep phone and emergency contact updates on their separate endpoints.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/me/phone": {
            "patch": {
                "summary": "Update your personal phone number",
                "tags": [
                    "Profile"
                ],
                "operationId": "mobileProfileUpdatePhone",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "phone": {
                                        "type": "string",
                                        "description": "max: 16"
                                    }
                                },
                                "required": [
                                    "phone"
                                ]
                            },
                            "example": {
                                "phone": "+2348012345678"
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Send phone in international format with a leading + and 8 to 15 digits. Spaces, parentheses and hyphens are removed before saving. Returns the complete updated profile in the same shape as GET /mobile/me, including the profile completeness marker. Saves only to your own tenant employee contact record; do not supply employee, candidate, user or tenant IDs. This is a contact update, not phone ownership verification.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "profile": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "employee_id": 3,
                                                "user": {
                                                    "id": 12,
                                                    "name": "Ada Worker",
                                                    "email": "worker@example.test",
                                                    "username": "worker.notifications",
                                                    "must_change_password": false
                                                },
                                                "tenant": {
                                                    "uuid": "c14db530-179d-48c7-94f4-ea58b66e4201",
                                                    "name": "Demo Tenant",
                                                    "timezone": "Africa/Lagos",
                                                    "country": "NG",
                                                    "currency": "NGN"
                                                },
                                                "role": "field-worker",
                                                "can_view_shifts": true,
                                                "employee": {
                                                    "id": 3,
                                                    "employee_no": "EMP-003",
                                                    "jobTitle": "Scaffolder",
                                                    "name": "Ada Worker",
                                                    "email": "worker@example.test",
                                                    "phone": "+2348012345678",
                                                    "status": "active",
                                                    "project_id": null,
                                                    "crew_id": null,
                                                    "emergencyContact": {
                                                        "fullName": "Bola Ahmed",
                                                        "relationship": "Sibling",
                                                        "phone": "+2348012345679"
                                                    }
                                                },
                                                "employment": {
                                                    "readOnly": true,
                                                    "jobTitle": "Scaffolder",
                                                    "employmentType": "full_time",
                                                    "department": "Site operations",
                                                    "startDate": "2026-11-01",
                                                    "status": "active",
                                                    "lifecycleStage": "active",
                                                    "supervisor": null,
                                                    "crew": null,
                                                    "pay": {
                                                        "rate": "250000.00",
                                                        "currency": "NGN",
                                                        "unit": "monthly",
                                                        "effectiveFrom": "2026-11-01"
                                                    }
                                                },
                                                "identity": {
                                                    "readOnly": true,
                                                    "image": null,
                                                    "country": "NG",
                                                    "documentType": null,
                                                    "documentNumber": null,
                                                    "dateOfBirth": null,
                                                    "nationalId": null,
                                                    "bankVerificationNumber": null,
                                                    "residentialAddress": null,
                                                    "verification": {
                                                        "status": "missing",
                                                        "items": [
                                                            {
                                                                "key": "national_id",
                                                                "label": "National ID (NIN slip or card)",
                                                                "status": "missing",
                                                                "documentId": null
                                                            },
                                                            {
                                                                "key": "proof_of_address",
                                                                "label": "Proof of address",
                                                                "status": "missing",
                                                                "documentId": null
                                                            }
                                                        ]
                                                    }
                                                },
                                                "payment": {
                                                    "readOnly": true,
                                                    "country": "NG",
                                                    "branchCode": null,
                                                    "bankCode": null,
                                                    "bankName": null,
                                                    "accountName": null,
                                                    "accountNumber": null,
                                                    "taxId": null,
                                                    "taxState": null,
                                                    "pensionProvider": null,
                                                    "pensionPin": null,
                                                    "housingFundNumber": null,
                                                    "updatedAt": null
                                                },
                                                "completeness": {
                                                    "isComplete": false,
                                                    "missing": [
                                                        "identity.dateOfBirth",
                                                        "identity.documentNumber",
                                                        "identity.residentialAddress",
                                                        "identity.imageDocumentId",
                                                        "payment.bankName",
                                                        "payment.accountName",
                                                        "payment.accountNumber",
                                                        "payment.bankCode"
                                                    ],
                                                    "workerMissing": [],
                                                    "sections": {
                                                        "employment": {
                                                            "complete": true,
                                                            "missing": [],
                                                            "managedBy": "tenant_admin"
                                                        },
                                                        "company": {
                                                            "complete": true,
                                                            "missing": [],
                                                            "managedBy": "tenant_admin"
                                                        },
                                                        "contact": {
                                                            "complete": true,
                                                            "missing": [],
                                                            "managedBy": "worker"
                                                        },
                                                        "identity": {
                                                            "complete": false,
                                                            "missing": [
                                                                "identity.dateOfBirth",
                                                                "identity.documentNumber",
                                                                "identity.residentialAddress",
                                                                "identity.imageDocumentId"
                                                            ],
                                                            "managedBy": "tenant_admin"
                                                        },
                                                        "payment": {
                                                            "complete": false,
                                                            "missing": [
                                                                "payment.bankName",
                                                                "payment.accountName",
                                                                "payment.accountNumber",
                                                                "payment.bankCode"
                                                            ],
                                                            "managedBy": "tenant_admin"
                                                        }
                                                    },
                                                    "onboarding": {
                                                        "enforced": false,
                                                        "enforcement": "none",
                                                        "managedBy": "tenant_admin",
                                                        "requiresSetup": false,
                                                        "setupComplete": false,
                                                        "profileIncomplete": true,
                                                        "nextStep": "identity_image",
                                                        "canUploadIdentityImage": true,
                                                        "canSubmit": true,
                                                        "status": "incomplete",
                                                        "submittedAt": null
                                                    }
                                                },
                                                "assigned_site": null,
                                                "current_shift": null,
                                                "next_shift": null
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid credentials or expired bearer token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    },
                                    "setupRequired": {
                                        "value": {
                                            "status": "error",
                                            "code": "password_change_required",
                                            "message": "Replace your temporary password to continue."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "phone": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Send phone in international format with a leading + and 8 to 15 digits. Spaces, parentheses and hyphens are removed before saving. Returns the complete updated profile in the same shape as GET /mobile/me, including the profile completeness marker. Saves only to your own tenant employee contact record; do not supply employee, candidate, user or tenant IDs. This is a contact update, not phone ownership verification.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/notification-preferences": {
            "get": {
                "summary": "Get your notification preferences",
                "tags": [
                    "Notifications"
                ],
                "operationId": "notificationPreferenceShow",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Return your push and email settings and muted notification categories.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "preferences": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "pushEnabled": true,
                                                "emailEnabled": false,
                                                "mutedCategories": []
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid credentials or expired bearer token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    },
                                    "setupRequired": {
                                        "value": {
                                            "status": "error",
                                            "code": "password_change_required",
                                            "message": "Replace your temporary password to continue."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "perPage": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Return your push and email settings and muted notification categories.",
                "x-generated": true
            },
            "put": {
                "summary": "Update your notification preferences",
                "tags": [
                    "Notifications"
                ],
                "operationId": "notificationPreferenceUpdate",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "emailEnabled": {
                                        "type": "boolean"
                                    },
                                    "mutedCategories": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "description": "max: 50"
                                        },
                                        "description": "max: 50"
                                    },
                                    "pushEnabled": {
                                        "type": "boolean"
                                    }
                                }
                            },
                            "example": {
                                "pushEnabled": true,
                                "emailEnabled": false,
                                "mutedCategories": []
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Send pushEnabled, emailEnabled or mutedCategories to change those preferences. In-app notifications remain available in your inbox.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "preferences": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "pushEnabled": true,
                                                "emailEnabled": false,
                                                "mutedCategories": []
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid credentials or expired bearer token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    },
                                    "setupRequired": {
                                        "value": {
                                            "status": "error",
                                            "code": "password_change_required",
                                            "message": "Replace your temporary password to continue."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "pushEnabled": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Send pushEnabled, emailEnabled or mutedCategories to change those preferences. In-app notifications remain available in your inbox.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/notifications": {
            "get": {
                "summary": "List your notifications",
                "tags": [
                    "Notifications"
                ],
                "operationId": "notificationIndex",
                "parameters": [
                    {
                        "name": "category",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "description": "max: 50"
                        }
                    },
                    {
                        "name": "perPage",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "description": "min: 1; max: 100"
                        }
                    },
                    {
                        "name": "severity",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "critical",
                                "warning",
                                "notice",
                                "info"
                            ]
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "all",
                                "unread",
                                "read"
                            ]
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Return your inbox and unread count. Filter by status, category or severity. Each item includes presentation.icon and presentation.tone for styling, plus data.eventType, action, screen, resourceType and resourceId when a record can be opened. Use these fields for mobile navigation; actionUrl is the tenant/web link.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "inbox": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "current_page": 1,
                                                "data": [
                                                    {
                                                        "id": "a14db530-179d-48c7-94f4-ea58b66e4201",
                                                        "type": "leave.approved",
                                                        "category": "leave",
                                                        "severity": "info",
                                                        "title": "Leave request approved",
                                                        "body": "Annual leave, 2027-08-02 to 2027-08-04",
                                                        "presentation": {
                                                            "icon": "calendar",
                                                            "tone": "neutral"
                                                        },
                                                        "actionUrl": "/my-leave",
                                                        "data": {
                                                            "leaveRequestId": "b14db530-179d-48c7-94f4-ea58b66e4201",
                                                            "eventType": "leave.approved",
                                                            "action": "approved",
                                                            "screen": "leave-detail",
                                                            "resourceType": "leave-request",
                                                            "resourceId": "b14db530-179d-48c7-94f4-ea58b66e4201"
                                                        },
                                                        "isRead": false,
                                                        "readAt": null,
                                                        "createdAt": "2027-07-01T09:00:00+00:00",
                                                        "relativeTime": "1 hour ago"
                                                    }
                                                ],
                                                "first_page_url": "/api/v1/mobile/notifications?page=1",
                                                "from": 1,
                                                "last_page": 1,
                                                "last_page_url": "/api/v1/mobile/notifications?page=1",
                                                "links": [
                                                    {
                                                        "url": null,
                                                        "label": "&laquo; Previous",
                                                        "active": false
                                                    },
                                                    {
                                                        "url": "/api/v1/mobile/notifications?page=1",
                                                        "label": "1",
                                                        "active": true
                                                    },
                                                    {
                                                        "url": null,
                                                        "label": "Next &raquo;",
                                                        "active": false
                                                    }
                                                ],
                                                "next_page_url": null,
                                                "path": "/api/v1/mobile/notifications",
                                                "per_page": 20,
                                                "prev_page_url": null,
                                                "to": 1,
                                                "total": 1
                                            },
                                            "meta": {
                                                "unreadCount": 1
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid credentials or expired bearer token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    },
                                    "setupRequired": {
                                        "value": {
                                            "status": "error",
                                            "code": "password_change_required",
                                            "message": "Replace your temporary password to continue."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "perPage": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Return your inbox and unread count. Filter by status, category or severity. Each item includes presentation.icon and presentation.tone for styling, plus data.eventType, action, screen, resourceType and resourceId when a record can be opened. Use these fields for mobile navigation; actionUrl is the tenant/web link.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/notifications/read-all": {
            "post": {
                "summary": "Mark your notifications as read",
                "tags": [
                    "Notifications"
                ],
                "operationId": "notificationReadAll",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "category": {
                                        "type": "string",
                                        "description": "max: 50"
                                    }
                                }
                            },
                            "example": {
                                "category": "leave"
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Mark all visible unread notifications read. Optionally send category to limit the operation to one notification category.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "markedRead": {
                                        "value": {
                                            "status": "success",
                                            "message": "1 notification(s) marked as read.",
                                            "data": {
                                                "updated": 1
                                            },
                                            "meta": {
                                                "unreadCount": 0
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid credentials or expired bearer token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    },
                                    "setupRequired": {
                                        "value": {
                                            "status": "error",
                                            "code": "password_change_required",
                                            "message": "Replace your temporary password to continue."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "category": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Mark all visible unread notifications read. Optionally send category to limit the operation to one notification category.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/notifications/stream": {
            "get": {
                "summary": "Listen for notification changes",
                "tags": [
                    "Notifications"
                ],
                "operationId": "notificationStreamInvoke",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "SSE frames, not JSON. Reconnect on stream.reconnect; use backoff on 429. End the stream on access.revoked.",
                        "content": {
                            "text/event-stream": {
                                "schema": {
                                    "type": "string"
                                },
                                "example": "event: notifications.changed\ndata: {\"unreadCount\":1,\"resync\":true}\n\n: heartbeat\n\nevent: stream.reconnect\ndata: {}\n\n"
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid credentials or expired bearer token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    },
                                    "setupRequired": {
                                        "value": {
                                            "status": "error",
                                            "code": "password_change_required",
                                            "message": "Replace your temporary password to continue."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "perPage": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Code delivery or streaming is unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "unavailable": {
                                        "value": {
                                            "status": "error",
                                            "message": "The service is temporarily unavailable."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Open an authenticated SSE connection with Accept: text/event-stream. On notifications.changed, refresh the summary and inbox. Reconnect after stream.reconnect; the stream does not mark items read.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/notifications/summary": {
            "get": {
                "summary": "Get the unread notification count",
                "tags": [
                    "Notifications"
                ],
                "operationId": "notificationSummary",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Return latestNotificationId and unreadCount. Poll this endpoint to detect inbox changes before fetching the full list.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "summary": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "latestNotificationId": "a14db530-179d-48c7-94f4-ea58b66e4201",
                                                "unreadCount": 1
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid credentials or expired bearer token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    },
                                    "setupRequired": {
                                        "value": {
                                            "status": "error",
                                            "code": "password_change_required",
                                            "message": "Replace your temporary password to continue."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "perPage": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Return latestNotificationId and unreadCount. Poll this endpoint to detect inbox changes before fetching the full list.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/notifications/{notification}/read": {
            "patch": {
                "summary": "Mark a notification as read",
                "tags": [
                    "Notifications"
                ],
                "operationId": "notificationMarkRead",
                "parameters": [
                    {
                        "name": "notification",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Use the notification UUID from the inbox. Marks that notification read for your account and returns the updated unread count.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "markedRead": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "a14db530-179d-48c7-94f4-ea58b66e4201",
                                                "type": "leave.approved",
                                                "category": "leave",
                                                "severity": "info",
                                                "title": "Leave request approved",
                                                "body": "Annual leave, 2027-08-02 to 2027-08-04",
                                                "presentation": {
                                                    "icon": "calendar",
                                                    "tone": "neutral"
                                                },
                                                "actionUrl": "/my-leave",
                                                "data": {
                                                    "leaveRequestId": "b14db530-179d-48c7-94f4-ea58b66e4201",
                                                    "eventType": "leave.approved",
                                                    "action": "approved",
                                                    "screen": "leave-detail",
                                                    "resourceType": "leave-request",
                                                    "resourceId": "b14db530-179d-48c7-94f4-ea58b66e4201"
                                                },
                                                "isRead": true,
                                                "readAt": "2027-07-01T10:00:00+00:00",
                                                "createdAt": "2027-07-01T09:00:00+00:00",
                                                "relativeTime": "1 hour ago"
                                            },
                                            "meta": {
                                                "unreadCount": 0
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid credentials or expired bearer token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    },
                                    "setupRequired": {
                                        "value": {
                                            "status": "error",
                                            "code": "password_change_required",
                                            "message": "Replace your temporary password to continue."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "perPage": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Use the notification UUID from the inbox. Marks that notification read for your account and returns the updated unread count.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/onboarding/face-enrollment": {
            "get": {
                "summary": "Get your selfie enrollment status",
                "tags": [
                    "Profile"
                ],
                "operationId": "faceAttendanceEnrollment",
                "parameters": [
                    {
                        "name": "photos[]",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "array",
                            "items": {
                                "type": "string",
                                "format": "binary",
                                "description": "max: 2048"
                            },
                            "description": "min: 3; max: 5"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Private enrollment or capture metadata. No vectors, templates, image paths or similarity scores are returned.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "latest": {
                                                    "id": "909394c9-bb80-4eac-9920-e164a2b5735a",
                                                    "employee_id": 3,
                                                    "status": "pending",
                                                    "photo_count": 3,
                                                    "reviewed_by": null,
                                                    "reviewed_at": null,
                                                    "review_note": null
                                                },
                                                "active": null,
                                                "reviewOnly": true
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired bearer token."
                    },
                    "403": {
                        "description": "Worker/HR/attendance permission required; reviewers cannot approve their own enrollment."
                    },
                    "404": {
                        "description": "The record is outside your employee or tenant scope."
                    },
                    "409": {
                        "description": "Pending enrollment already exists, already reviewed, capture expired/used, or photo binding changed."
                    },
                    "422": {
                        "description": "Invalid JPEG, image count/size, action or enrollment quality."
                    },
                    "429": {
                        "description": "Capture/enrollment rate limit reached."
                    },
                    "503": {
                        "description": "Upload scanner, enrollment processing or enrollment encryption unavailable. A sidecar outage during attendance photo processing instead produces a ready capture requiring human review."
                    }
                },
                "description": "Returns latest and active enrollment metadata and reviewOnly=true. An approved identity-card image is separate from selfie enrollment. HR must approve the selfies before they become an active reference.",
                "x-generated": true
            },
            "post": {
                "summary": "Submit onboarding selfies to HR",
                "tags": [
                    "Profile"
                ],
                "operationId": "faceAttendanceEnrollment2",
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "photos": {
                                        "type": "array",
                                        "minItems": 3,
                                        "maxItems": 5,
                                        "items": {
                                            "type": "string",
                                            "format": "binary"
                                        },
                                        "description": "3–5 separate JPEG selfies, each at most 5 MiB, using photos[] fields."
                                    }
                                },
                                "required": [
                                    "photos"
                                ]
                            },
                            "example": {
                                "photos": [
                                    "(binary JPEG selfie 1)",
                                    "(binary JPEG selfie 2)",
                                    "(binary JPEG selfie 3)"
                                ]
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Private enrollment or capture metadata. No vectors, templates, image paths or similarity scores are returned.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "909394c9-bb80-4eac-9920-e164a2b5735a",
                                                "employee_id": 3,
                                                "status": "pending",
                                                "photo_count": 3,
                                                "reviewed_by": null,
                                                "reviewed_at": null,
                                                "review_note": null
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired bearer token."
                    },
                    "403": {
                        "description": "Worker/HR/attendance permission required; reviewers cannot approve their own enrollment."
                    },
                    "404": {
                        "description": "The record is outside your employee or tenant scope."
                    },
                    "409": {
                        "description": "Pending enrollment already exists, already reviewed, capture expired/used, or photo binding changed."
                    },
                    "422": {
                        "description": "Invalid JPEG, image count/size, action or enrollment quality."
                    },
                    "429": {
                        "description": "Capture/enrollment rate limit reached."
                    },
                    "503": {
                        "description": "Upload scanner, enrollment processing or enrollment encryption unavailable. A sidecar outage during attendance photo processing instead produces a ready capture requiring human review."
                    }
                },
                "description": "Upload 3–5 separate JPEG files as photos[], each up to 5 MiB subject to server upload limits. The local sidecar checks frame quality/consistency. Selfies use authenticated Cloudinary storage when configured; the encrypted template remains in the backend database. A valid template is saved as pending and HR is notified. A pending enrollment must be reviewed before another submission; an existing approved reference remains active during replacement review. No employee ID is accepted.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/onboarding/identity-image": {
            "post": {
                "summary": "Upload an identity-card image for optional self-service",
                "tags": [
                    "Profile"
                ],
                "operationId": "mobileProfileOnboardingImage",
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "file": {
                                        "type": "string",
                                        "format": "binary",
                                        "description": "max: 2048"
                                    }
                                },
                                "required": [
                                    "file"
                                ]
                            },
                            "example": {
                                "file": "(binary JPG, PNG or WebP identity-card image)"
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Send file as multipart/form-data: a real JPG, PNG or WebP image within the employee-document upload limit. Saves a private, owner-linked Identification document with pending review status in the same document store used by tenant HR. Use its id as identity.imageDocumentId when submitting setup. An image supplied by HR or submitted through self-service is read-only while pending or verified. Missing or HR-rejected images can be replaced. Replacement of a submitted image notifies HR.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "identityImage": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "17",
                                                "kind": "document",
                                                "employeeId": 3,
                                                "uploadedBy": 12,
                                                "name": "identity.jpg",
                                                "category": "Identification",
                                                "uploadedAt": "2026-11-09T10:00:00+00:00",
                                                "fileType": "JPG",
                                                "downloadUrl": "/api/v1/mobile/documents/17/download",
                                                "identityType": "national_id",
                                                "verificationStatus": "pending"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "The submitted identity image is read-only unless HR rejected it or it is missing.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "locked": {
                                        "value": {
                                            "message": "Your identity image is read-only. Ask HR for corrections."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Image scanning or private storage is unavailable; the image was not saved.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "unavailable": {
                                        "value": {
                                            "message": "Document scanning is temporarily unavailable. Your file was not saved. Please try again later."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid credentials or expired bearer token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    },
                                    "setupRequired": {
                                        "value": {
                                            "status": "error",
                                            "code": "password_change_required",
                                            "message": "Replace your temporary password to continue."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "file": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Send file as multipart/form-data: a real JPG, PNG or WebP image within the employee-document upload limit. Saves a private, owner-linked Identification document with pending review status in the same document store used by tenant HR. Use its id as identity.imageDocumentId when submitting setup. An image supplied by HR or submitted through self-service is read-only while pending or verified. Missing or HR-rejected images can be replaced. Replacement of a submitted image notifies HR.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/onboarding/profile": {
            "get": {
                "summary": "Get initial identity and payment requirements",
                "tags": [
                    "Profile"
                ],
                "operationId": "mobileProfileOnboardingShow",
                "parameters": [
                    {
                        "name": "country",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "description": "max: 100"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "After permanent password setup, get the effective country, document types, bank choices, required fields and current completeness. Optional country previews another country; countries lists the supported country codes and names from the shared catalog. The onboarding country overrides the tenant default. Nigeria uses configured bank codes and NUBAN/NIN formats; other countries use generic format validation and a bank name. Empty bank choices mean no curated bank directory is configured, not that bank accounts are verified.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "requirements": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "country": "NG",
                                                "countrySource": "tenant_default",
                                                "countries": [
                                                    {
                                                        "code": "NG",
                                                        "name": "Nigeria"
                                                    },
                                                    {
                                                        "code": "JM",
                                                        "name": "Jamaica"
                                                    },
                                                    {
                                                        "code": "GY",
                                                        "name": "Guyana"
                                                    }
                                                ],
                                                "validationMode": "nigeria_format_rules",
                                                "documentTypes": [
                                                    "national_id",
                                                    "passport",
                                                    "tax_id",
                                                    "other"
                                                ],
                                                "banks": [
                                                    {
                                                        "code": "058",
                                                        "name": "Guaranty Trust Bank (GTBank)"
                                                    }
                                                ],
                                                "required": [
                                                    "country",
                                                    "identity.dateOfBirth",
                                                    "identity.documentType",
                                                    "identity.documentNumber",
                                                    "identity.residentialAddress",
                                                    "identity.imageDocumentId",
                                                    "payment.accountName",
                                                    "payment.accountNumber",
                                                    "payment.bankCode"
                                                ],
                                                "accountNumberFormat": "10 digits",
                                                "completeness": {
                                                    "isComplete": false,
                                                    "missing": [
                                                        "identity.dateOfBirth",
                                                        "identity.documentNumber",
                                                        "identity.residentialAddress",
                                                        "identity.imageDocumentId",
                                                        "payment.bankName",
                                                        "payment.accountName",
                                                        "payment.accountNumber",
                                                        "payment.bankCode"
                                                    ],
                                                    "workerMissing": [],
                                                    "sections": {
                                                        "employment": {
                                                            "complete": true,
                                                            "missing": [],
                                                            "managedBy": "tenant_admin"
                                                        },
                                                        "company": {
                                                            "complete": true,
                                                            "missing": [],
                                                            "managedBy": "tenant_admin"
                                                        },
                                                        "contact": {
                                                            "complete": true,
                                                            "missing": [],
                                                            "managedBy": "worker"
                                                        },
                                                        "identity": {
                                                            "complete": false,
                                                            "missing": [
                                                                "identity.dateOfBirth",
                                                                "identity.documentNumber",
                                                                "identity.residentialAddress",
                                                                "identity.imageDocumentId"
                                                            ],
                                                            "managedBy": "tenant_admin"
                                                        },
                                                        "payment": {
                                                            "complete": false,
                                                            "missing": [
                                                                "payment.bankName",
                                                                "payment.accountName",
                                                                "payment.accountNumber",
                                                                "payment.bankCode"
                                                            ],
                                                            "managedBy": "tenant_admin"
                                                        }
                                                    },
                                                    "onboarding": {
                                                        "enforced": false,
                                                        "enforcement": "none",
                                                        "managedBy": "tenant_admin",
                                                        "requiresSetup": false,
                                                        "setupComplete": false,
                                                        "profileIncomplete": true,
                                                        "nextStep": "identity_image",
                                                        "canUploadIdentityImage": true,
                                                        "canSubmit": true,
                                                        "status": "incomplete",
                                                        "submittedAt": null
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid credentials or expired bearer token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    },
                                    "setupRequired": {
                                        "value": {
                                            "status": "error",
                                            "code": "password_change_required",
                                            "message": "Replace your temporary password to continue."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "perPage": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "After permanent password setup, get the effective country, document types, bank choices, required fields and current completeness. Optional country previews another country; countries lists the supported country codes and names from the shared catalog. The onboarding country overrides the tenant default. Nigeria uses configured bank codes and NUBAN/NIN formats; other countries use generic format validation and a bank name. Empty bank choices mean no curated bank directory is configured, not that bank accounts are verified.",
                "x-generated": true
            },
            "put": {
                "summary": "Submit optional initial identity and payment details",
                "tags": [
                    "Profile"
                ],
                "operationId": "mobileProfileOnboardingUpdate",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "country": {
                                        "type": "string",
                                        "description": "Onboarding country; omitted values use the tenant country. Nigeria/NG, Jamaica/JM and Guyana/GY are normalized."
                                    },
                                    "identity": {
                                        "type": "object",
                                        "properties": {
                                            "dateOfBirth": {
                                                "type": "string",
                                                "format": "date"
                                            },
                                            "documentNumber": {
                                                "type": "string",
                                                "description": "max: 64"
                                            },
                                            "documentType": {
                                                "type": "string",
                                                "enum": [
                                                    "national_id",
                                                    "passport",
                                                    "tax_id",
                                                    "other"
                                                ]
                                            },
                                            "imageDocumentId": {
                                                "type": "integer",
                                                "description": "min: 1"
                                            },
                                            "residentialAddress": {
                                                "type": "string",
                                                "description": "max: 1000"
                                            }
                                        },
                                        "required": [
                                            "dateOfBirth",
                                            "documentNumber",
                                            "documentType",
                                            "imageDocumentId",
                                            "residentialAddress"
                                        ]
                                    },
                                    "payment": {
                                        "type": "object",
                                        "properties": {
                                            "accountName": {
                                                "type": "string",
                                                "description": "max: 255"
                                            },
                                            "accountNumber": {
                                                "type": "string"
                                            },
                                            "bankCode": {
                                                "type": "string",
                                                "nullable": true,
                                                "description": "max: 10"
                                            },
                                            "bankName": {
                                                "type": "string",
                                                "description": "max: 255"
                                            },
                                            "branchCode": {
                                                "type": "string",
                                                "nullable": true,
                                                "description": "max: 50"
                                            },
                                            "taxId": {
                                                "type": "string",
                                                "nullable": true,
                                                "description": "max: 64"
                                            }
                                        },
                                        "required": [
                                            "accountName",
                                            "accountNumber"
                                        ],
                                        "anyOf": [
                                            {
                                                "required": [
                                                    "bankCode"
                                                ]
                                            },
                                            {
                                                "required": [
                                                    "bankName"
                                                ]
                                            }
                                        ],
                                        "description": "Nigeria requires a configured bankCode and a 10-digit accountNumber. Other countries require bankName and use generic alphanumeric account format checks."
                                    }
                                },
                                "required": [
                                    "identity",
                                    "payment"
                                ]
                            },
                            "example": {
                                "country": "NG",
                                "identity": {
                                    "dateOfBirth": "1994-04-20",
                                    "documentType": "national_id",
                                    "documentNumber": "12345678901",
                                    "residentialAddress": "12 Site Road",
                                    "imageDocumentId": 17
                                },
                                "payment": {
                                    "bankCode": "058",
                                    "accountName": "Ada Worker",
                                    "accountNumber": "0123456789"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "After permanent password setup, send identity and payment objects. Country defaults to the tenant country when omitted. Nigeria requires bankCode; other countries require bankName. Supply dateOfBirth, documentType, documentNumber, residentialAddress, the owned identity.imageDocumentId from the identity-image upload, accountName and accountNumber. Existing saved values cannot be overwritten. Successful submission locks worker edits; an exact normalized retry returns the profile and changed retries return 409. HR can correct saved records. The response is the full expanded mobile profile. Submission notifies authorised HR/tenant reviewers. Tenant staff manage profile setup. This optional submission fills missing values for clients that still support self-service. Profile completeness is informational. Phone, emergency contact, employment, pay rate and verification decisions are managed separately. This endpoint checks formats and does not verify bank ownership or establish country payroll compliance.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "profile": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "employee_id": 3,
                                                "user": {
                                                    "id": 12,
                                                    "name": "Ada Worker",
                                                    "email": "worker@example.test",
                                                    "username": "worker.notifications",
                                                    "must_change_password": false
                                                },
                                                "tenant": {
                                                    "uuid": "c14db530-179d-48c7-94f4-ea58b66e4201",
                                                    "name": "Demo Tenant",
                                                    "timezone": "Africa/Lagos",
                                                    "country": "NG",
                                                    "currency": "NGN"
                                                },
                                                "role": "field-worker",
                                                "can_view_shifts": true,
                                                "employee": {
                                                    "id": 3,
                                                    "employee_no": "EMP-003",
                                                    "jobTitle": "Scaffolder",
                                                    "name": "Ada Worker",
                                                    "email": "worker@example.test",
                                                    "phone": "+2348000000000",
                                                    "status": "active",
                                                    "project_id": null,
                                                    "crew_id": null,
                                                    "emergencyContact": {
                                                        "fullName": "Bola Ahmed",
                                                        "relationship": "Sibling",
                                                        "phone": "+2348012345679"
                                                    }
                                                },
                                                "employment": {
                                                    "readOnly": true,
                                                    "jobTitle": "Scaffolder",
                                                    "employmentType": "full_time",
                                                    "department": "Site operations",
                                                    "startDate": "2026-11-01",
                                                    "status": "active",
                                                    "lifecycleStage": "active",
                                                    "supervisor": null,
                                                    "crew": null,
                                                    "pay": {
                                                        "rate": "250000.00",
                                                        "currency": "NGN",
                                                        "unit": "monthly",
                                                        "effectiveFrom": "2026-11-01"
                                                    }
                                                },
                                                "identity": {
                                                    "readOnly": true,
                                                    "image": {
                                                        "id": "17",
                                                        "kind": "document",
                                                        "employeeId": 3,
                                                        "uploadedBy": 12,
                                                        "name": "identity.jpg",
                                                        "category": "Identification",
                                                        "uploadedAt": "2026-11-09T10:00:00+00:00",
                                                        "fileType": "JPG",
                                                        "downloadUrl": "/api/v1/mobile/documents/17/download",
                                                        "verificationStatus": "pending",
                                                        "reviewNote": null
                                                    },
                                                    "country": "NG",
                                                    "documentType": "national_id",
                                                    "documentNumber": "12345678901",
                                                    "dateOfBirth": "1994-04-20",
                                                    "nationalId": "12345678901",
                                                    "bankVerificationNumber": null,
                                                    "residentialAddress": "12 Site Road",
                                                    "verification": {
                                                        "status": "missing",
                                                        "items": [
                                                            {
                                                                "key": "national_id",
                                                                "label": "National ID (NIN slip or card)",
                                                                "status": "missing",
                                                                "documentId": null
                                                            },
                                                            {
                                                                "key": "proof_of_address",
                                                                "label": "Proof of address",
                                                                "status": "missing",
                                                                "documentId": null
                                                            }
                                                        ]
                                                    }
                                                },
                                                "payment": {
                                                    "readOnly": true,
                                                    "country": "NG",
                                                    "branchCode": null,
                                                    "bankCode": "058",
                                                    "bankName": "Guaranty Trust Bank (GTBank)",
                                                    "accountName": "Ada Worker",
                                                    "accountNumber": "0123456789",
                                                    "taxId": null,
                                                    "taxState": null,
                                                    "pensionProvider": null,
                                                    "pensionPin": null,
                                                    "housingFundNumber": null,
                                                    "updatedAt": "2026-11-09T10:00:00+00:00"
                                                },
                                                "completeness": {
                                                    "isComplete": true,
                                                    "missing": [],
                                                    "workerMissing": [],
                                                    "sections": {
                                                        "employment": {
                                                            "complete": true,
                                                            "missing": [],
                                                            "managedBy": "tenant_admin"
                                                        },
                                                        "company": {
                                                            "complete": true,
                                                            "missing": [],
                                                            "managedBy": "tenant_admin"
                                                        },
                                                        "contact": {
                                                            "complete": true,
                                                            "missing": [],
                                                            "managedBy": "worker"
                                                        },
                                                        "identity": {
                                                            "complete": true,
                                                            "missing": [],
                                                            "managedBy": "tenant_admin"
                                                        },
                                                        "payment": {
                                                            "complete": true,
                                                            "missing": [],
                                                            "managedBy": "tenant_admin"
                                                        }
                                                    },
                                                    "onboarding": {
                                                        "enforced": false,
                                                        "enforcement": "none",
                                                        "managedBy": "tenant_admin",
                                                        "requiresSetup": false,
                                                        "setupComplete": true,
                                                        "profileIncomplete": false,
                                                        "nextStep": null,
                                                        "canUploadIdentityImage": false,
                                                        "canSubmit": false,
                                                        "status": "submitted",
                                                        "submittedAt": "2026-11-09T10:00:00+00:00"
                                                    }
                                                },
                                                "assigned_site": null,
                                                "current_shift": null,
                                                "next_shift": null
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid credentials or expired bearer token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    },
                                    "setupRequired": {
                                        "value": {
                                            "status": "error",
                                            "code": "password_change_required",
                                            "message": "Replace your temporary password to continue."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "country": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "Initial details are already supplied or a retry changes the submitted data. Ask HR for corrections.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "locked": {
                                        "value": {
                                            "message": "Identity and payment details have already been submitted. Ask HR to correct them."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "After permanent password setup, send identity and payment objects. Country defaults to the tenant country when omitted. Nigeria requires bankCode; other countries require bankName. Supply dateOfBirth, documentType, documentNumber, residentialAddress, the owned identity.imageDocumentId from the identity-image upload, accountName and accountNumber. Existing saved values cannot be overwritten. Successful submission locks worker edits; an exact normalized retry returns the profile and changed retries return 409. HR can correct saved records. The response is the full expanded mobile profile. Submission notifies authorised HR/tenant reviewers. Tenant staff manage profile setup. This optional submission fills missing values for clients that still support self-service. Profile completeness is informational. Phone, emergency contact, employment, pay rate and verification decisions are managed separately. This endpoint checks formats and does not verify bank ownership or establish country payroll compliance.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/onboarding/status": {
            "get": {
                "summary": "Check profile completeness",
                "tags": [
                    "Profile"
                ],
                "operationId": "mobileProfileOnboardingStatus",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Return profileIncomplete and missing field names without returning identity or bank values. Saved details count whether entered by tenant staff or the worker. Display the marker as an informational reminder. requiresSetup is false and enforcement is none for profile completion. Password setup, worker membership and record ownership still apply.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "setupStatus": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "onboarding": {
                                                    "enforced": false,
                                                    "enforcement": "none",
                                                    "managedBy": "tenant_admin",
                                                    "requiresSetup": false,
                                                    "setupComplete": false,
                                                    "profileIncomplete": true,
                                                    "nextStep": "identity_image",
                                                    "canUploadIdentityImage": true,
                                                    "canSubmit": true,
                                                    "status": "incomplete",
                                                    "submittedAt": null
                                                },
                                                "missing": [
                                                    "identity.dateOfBirth",
                                                    "identity.documentNumber",
                                                    "identity.residentialAddress",
                                                    "identity.imageDocumentId",
                                                    "payment.bankName",
                                                    "payment.accountName",
                                                    "payment.accountNumber",
                                                    "payment.bankCode"
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid credentials or expired bearer token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    },
                                    "setupRequired": {
                                        "value": {
                                            "status": "error",
                                            "code": "password_change_required",
                                            "message": "Replace your temporary password to continue."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "perPage": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Return profileIncomplete and missing field names without returning identity or bank values. Saved details count whether entered by tenant staff or the worker. Display the marker as an informational reminder. requiresSetup is false and enforcement is none for profile completion. Password setup, worker membership and record ownership still apply.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/open-shift-claims": {
            "get": {
                "summary": "List your open shift claim history",
                "tags": [
                    "Shifts"
                ],
                "operationId": "mobileOpenShiftHistory",
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        }
                    },
                    {
                        "name": "perPage",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 50,
                            "default": 20
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Returns only your claim receipts, newest first, with current shift and assignment status. Claim status approved records the original successful claim; a later decline, cancellation or unassignment is reflected in assignmentStatus/shift.status and does not rewrite that receipt. Assignment fields describe the current booking, not a historical booking snapshot. Paginate with page/perPage (default 20, maximum 50).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": [
                                                {
                                                    "id": 4,
                                                    "shiftId": 9,
                                                    "status": "approved",
                                                    "notes": "Available for cover",
                                                    "claimedAt": "2026-11-10T08:00:00+00:00",
                                                    "assignmentId": 21,
                                                    "assignmentStatus": "confirmed",
                                                    "shift": {
                                                        "id": 9,
                                                        "title": "Open site shift",
                                                        "startTime": "2026-11-11T08:00:00+00:00",
                                                        "endTime": "2026-11-11T16:00:00+00:00",
                                                        "status": "filled"
                                                    }
                                                }
                                            ],
                                            "meta": {
                                                "current_page": 1,
                                                "last_page": 1,
                                                "per_page": 20,
                                                "total": 1
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Worker bearer token is missing or expired."
                    },
                    "403": {
                        "description": "Inactive worker, password setup, scheduling module or plan restriction."
                    },
                    "404": {
                        "description": "Shift is unpublished or outside the worker organisation."
                    },
                    "422": {
                        "description": "Missing revision, invalid notes or forbidden ownership fields; scheduling eligibility failed."
                    },
                    "429": {
                        "description": "Rate limited. Retry with backoff."
                    }
                },
                "description": "Returns only your claim receipts, newest first, with current shift and assignment status. Claim status approved records the original successful claim; a later decline, cancellation or unassignment is reflected in assignmentStatus/shift.status and does not rewrite that receipt. Assignment fields describe the current booking, not a historical booking snapshot. Paginate with page/perPage (default 20, maximum 50).",
                "x-generated": true
            }
        },
        "/api/v1/mobile/open-shifts": {
            "get": {
                "summary": "Browse open shift opportunities",
                "tags": [
                    "Shifts"
                ],
                "operationId": "mobileOpenShiftIndex",
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        }
                    },
                    {
                        "name": "perPage",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 50,
                            "default": 20
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated published shifts in your organisation that have vacant places and have not ended, excluding your current staffing assignments. Each row contains your own canClaim and eligibilityReason; ineligible opportunities can remain visible with claiming disabled. Checks use your employee ID, certificates, leave/unavailability, overlaps, rest, weekly cap and configured travel rules. No other worker profiles, scores, pay rates or candidate lists are returned. page/perPage defaults to 20 and is capped at 50.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": [
                                                {
                                                    "id": 9,
                                                    "title": "Open site shift",
                                                    "revision": 1,
                                                    "startTime": "2026-11-11T08:00:00+00:00",
                                                    "endTime": "2026-11-11T16:00:00+00:00",
                                                    "status": "open",
                                                    "placesAvailable": 1,
                                                    "requiredCertifications": [],
                                                    "project": {
                                                        "id": 2,
                                                        "name": "Site"
                                                    },
                                                    "crew": null,
                                                    "canClaim": true,
                                                    "eligibilityReason": null,
                                                    "timezone": "Africa/Lagos"
                                                }
                                            ],
                                            "meta": {
                                                "current_page": 1,
                                                "last_page": 1,
                                                "per_page": 20,
                                                "total": 1
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Worker bearer token is missing or expired."
                    },
                    "403": {
                        "description": "Inactive worker, password setup, scheduling module or plan restriction."
                    },
                    "404": {
                        "description": "Shift is unpublished or outside the worker organisation."
                    },
                    "422": {
                        "description": "Missing revision, invalid notes or forbidden ownership fields; scheduling eligibility failed."
                    },
                    "429": {
                        "description": "Rate limited. Retry with backoff."
                    }
                },
                "description": "Paginated published shifts in your organisation that have vacant places and have not ended, excluding your current staffing assignments. Each row contains your own canClaim and eligibilityReason; ineligible opportunities can remain visible with claiming disabled. Checks use your employee ID, certificates, leave/unavailability, overlaps, rest, weekly cap and configured travel rules. No other worker profiles, scores, pay rates or candidate lists are returned. page/perPage defaults to 20 and is capped at 50.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/open-shifts/{shift}": {
            "get": {
                "summary": "View an open shift opportunity",
                "tags": [
                    "Shifts"
                ],
                "operationId": "mobileOpenShiftShow",
                "parameters": [
                    {
                        "name": "shift",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "description": "Published opportunity shift id, not assignmentId."
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Returns published shift details in your organisation, its revision, remaining places and your eligibility. A cached opportunity that has filled or ended returns canClaim=false. Draft or foreign-tenant shifts return 404. Eligibility and capacity are checked again when claiming.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": 9,
                                                "title": "Open site shift",
                                                "revision": 1,
                                                "startTime": "2026-11-11T08:00:00+00:00",
                                                "endTime": "2026-11-11T16:00:00+00:00",
                                                "status": "open",
                                                "placesAvailable": 1,
                                                "requiredCertifications": [],
                                                "project": {
                                                    "id": 2,
                                                    "name": "Site"
                                                },
                                                "crew": null,
                                                "canClaim": true,
                                                "eligibilityReason": null,
                                                "timezone": "Africa/Lagos"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Worker bearer token is missing or expired."
                    },
                    "403": {
                        "description": "Inactive worker, password setup, scheduling module or plan restriction."
                    },
                    "404": {
                        "description": "Shift is unpublished or outside the worker organisation."
                    },
                    "422": {
                        "description": "Missing revision, invalid notes or forbidden ownership fields; scheduling eligibility failed."
                    },
                    "429": {
                        "description": "Rate limited. Retry with backoff."
                    }
                },
                "description": "Returns published shift details in your organisation, its revision, remaining places and your eligibility. A cached opportunity that has filled or ended returns canClaim=false. Draft or foreign-tenant shifts return 404. Eligibility and capacity are checked again when claiming.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/open-shifts/{shift}/claim": {
            "post": {
                "summary": "Claim an open shift for yourself",
                "tags": [
                    "Shifts"
                ],
                "operationId": "mobileOpenShiftClaim",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "revision"
                                ],
                                "properties": {
                                    "revision": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "description": "The revision displayed to the worker."
                                    },
                                    "notes": {
                                        "type": "string",
                                        "maxLength": 1000
                                    }
                                }
                            },
                            "example": {
                                "revision": 1,
                                "notes": "Available for cover"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "shift",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "description": "Published opportunity shift id, not assignmentId."
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Send revision from the opportunity response and optional notes up to 1000 characters. Employee identity is derived from the worker token. A valid claim immediately creates a confirmed assignment; there is no pending manager approval or second accept step. Shift and employee locks protect capacity and conflict checks; all writes, audit and notification outbox commit together. Returns claim id, assignmentId and confirmed assignment status. The same currently confirmed claim and notes replay with 200; new claims return 201. Changed revision, full/closed shift, duplicate assignment or changed retry notes return 409; eligibility failures return 422. After a timeout read your roster/claim history before retrying.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": 4,
                                                "shiftId": 9,
                                                "employeeId": 3,
                                                "status": "approved",
                                                "assignmentId": 21,
                                                "assignmentStatus": "confirmed",
                                                "notes": "Available for cover",
                                                "claimedAt": "2026-11-10T08:00:00+00:00"
                                            },
                                            "replayed": false
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Worker bearer token is missing or expired."
                    },
                    "403": {
                        "description": "Inactive worker, password setup, scheduling module or plan restriction."
                    },
                    "404": {
                        "description": "Shift is unpublished or outside the worker organisation."
                    },
                    "422": {
                        "description": "Missing revision, invalid notes or forbidden ownership fields; scheduling eligibility failed."
                    },
                    "429": {
                        "description": "Rate limited. Retry with backoff."
                    },
                    "200": {
                        "description": "Existing confirmed claim replayed.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": 4,
                                                "shiftId": 9,
                                                "employeeId": 3,
                                                "status": "approved",
                                                "assignmentId": 21,
                                                "assignmentStatus": "confirmed",
                                                "notes": "Available for cover",
                                                "claimedAt": "2026-11-10T08:00:00+00:00"
                                            },
                                            "replayed": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "Stale revision, no remaining places, ended/cancelled shift, overlapping assignment or conflicting retry. Refresh opportunity, roster and claim history."
                    }
                },
                "description": "Send revision from the opportunity response and optional notes up to 1000 characters. Employee identity is derived from the worker token. A valid claim immediately creates a confirmed assignment; there is no pending manager approval or second accept step. Shift and employee locks protect capacity and conflict checks; all writes, audit and notification outbox commit together. Returns claim id, assignmentId and confirmed assignment status. The same currently confirmed claim and notes replay with 200; new claims return 201. Changed revision, full/closed shift, duplicate assignment or changed retry notes return 409; eligibility failures return 422. After a timeout read your roster/claim history before retrying.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/shift-assignments/{assignment}": {
            "get": {
                "summary": "View your shift assignment",
                "tags": [
                    "Shifts"
                ],
                "operationId": "shiftResponseShow",
                "parameters": [
                    {
                        "name": "assignment",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Use assignmentId from GET mobile/shifts. Returns shift details, revision, response, canDecline and canSwap. An assigned shift is already on your roster. canSwap is false when the shift has no project. Another worker’s assignment or an unpublished shift returns 404.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "data": {
                                                "id": 21,
                                                "assignmentId": 21,
                                                "canSwap": true,
                                                "canDecline": true,
                                                "canRespond": true,
                                                "response": "assigned",
                                                "declineReason": null,
                                                "respondedAt": null,
                                                "notificationStatus": null,
                                                "messages": 0,
                                                "shift": {
                                                    "id": 15,
                                                    "title": "Morning shift",
                                                    "revision": 1,
                                                    "requiredSkills": [],
                                                    "notes": null,
                                                    "publishedAt": "2027-07-25T10:00:00+00:00",
                                                    "start": "2027-08-01T08:00:00+00:00",
                                                    "end": "2027-08-01T16:00:00+00:00",
                                                    "status": "filled",
                                                    "project": "Site A",
                                                    "crew": null
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Worker account, scheduling access or plan is not eligible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Worker account, scheduling access or plan is not eligible."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Assignment or swap not found in your employee scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Assignment or swap not found in your employee scope."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "The shift changed or is no longer open for this action.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The shift changed or is no longer open for this action."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid input, ineligible colleague or duplicate pending request.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Invalid input, ineligible colleague or duplicate pending request."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Use assignmentId from GET mobile/shifts. Returns shift details, revision, response, canDecline and canSwap. An assigned shift is already on your roster. canSwap is false when the shift has no project. Another worker’s assignment or an unpublished shift returns 404.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/shift-assignments/{assignment}/accept": {
            "post": {
                "summary": "Record a legacy shift acceptance",
                "tags": [
                    "Shifts"
                ],
                "operationId": "shiftResponseAccept",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "revision": {
                                        "type": "integer",
                                        "description": "min: 1"
                                    }
                                }
                            },
                            "example": {
                                "revision": 1
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "assignment",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Compatibility action for older clients. Published assignments appear on the roster immediately. Current clients use decline or request a swap.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "data": {
                                                "id": 21,
                                                "assignmentId": 21,
                                                "canSwap": true,
                                                "canDecline": true,
                                                "canRespond": true,
                                                "response": "accepted",
                                                "declineReason": null,
                                                "respondedAt": null,
                                                "notificationStatus": null,
                                                "messages": 0,
                                                "shift": {
                                                    "id": 15,
                                                    "title": "Morning shift",
                                                    "revision": 1,
                                                    "requiredSkills": [],
                                                    "notes": null,
                                                    "publishedAt": "2027-07-25T10:00:00+00:00",
                                                    "start": "2027-08-01T08:00:00+00:00",
                                                    "end": "2027-08-01T16:00:00+00:00",
                                                    "status": "filled",
                                                    "project": "Site A",
                                                    "crew": null
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Worker account, scheduling access or plan is not eligible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Worker account, scheduling access or plan is not eligible."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Assignment or swap not found in your employee scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Assignment or swap not found in your employee scope."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "The shift changed or is no longer open for this action.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The shift changed or is no longer open for this action."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid input, ineligible colleague or duplicate pending request.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Invalid input, ineligible colleague or duplicate pending request."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "deprecated": true,
                "description": "Compatibility action for older clients. Published assignments appear on the roster immediately. Current clients use decline or request a swap.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/shift-assignments/{assignment}/decline": {
            "post": {
                "summary": "Decline your shift",
                "tags": [
                    "Shifts"
                ],
                "operationId": "shiftResponseDecline",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "reason": {
                                        "type": "string",
                                        "description": "max: 1000"
                                    },
                                    "revision": {
                                        "type": "integer",
                                        "description": "min: 1"
                                    }
                                },
                                "required": [
                                    "reason"
                                ]
                            },
                            "example": {
                                "reason": "Unavailable for this shift",
                                "revision": 1
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "assignment",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Use your assignmentId. Send a non-empty reason of up to 1000 characters and optionally the shift revision. The decline releases the place for reassignment, notifies the scheduler and stays visible in your shift history. A cancelled, completed or ended shift returns 409.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "data": {
                                                "id": 21,
                                                "assignmentId": 21,
                                                "canSwap": false,
                                                "canDecline": false,
                                                "canRespond": false,
                                                "response": "declined",
                                                "declineReason": "Unavailable for this shift",
                                                "respondedAt": null,
                                                "notificationStatus": null,
                                                "messages": 0,
                                                "shift": {
                                                    "id": 15,
                                                    "title": "Morning shift",
                                                    "revision": 1,
                                                    "requiredSkills": [],
                                                    "notes": null,
                                                    "publishedAt": "2027-07-25T10:00:00+00:00",
                                                    "start": "2027-08-01T08:00:00+00:00",
                                                    "end": "2027-08-01T16:00:00+00:00",
                                                    "status": "filled",
                                                    "project": "Site A",
                                                    "crew": null
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Worker account, scheduling access or plan is not eligible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Worker account, scheduling access or plan is not eligible."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Assignment or swap not found in your employee scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Assignment or swap not found in your employee scope."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "The shift changed or is no longer open for this action.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The shift changed or is no longer open for this action."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid input, ineligible colleague or duplicate pending request.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Invalid input, ineligible colleague or duplicate pending request."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Use your assignmentId. Send a non-empty reason of up to 1000 characters and optionally the shift revision. The decline releases the place for reassignment, notifies the scheduler and stays visible in your shift history. A cancelled, completed or ended shift returns 409.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/shift-assignments/{assignment}/history": {
            "get": {
                "summary": "View your shift timeline",
                "tags": [
                    "Shifts"
                ],
                "operationId": "shiftResponseHistory",
                "parameters": [
                    {
                        "name": "assignment",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Use your assignmentId to view dated roster events such as assignment, publication, schedule changes, decline and swap-out. The timeline omits legacy acceptance events.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "data": [
                                                {
                                                    "id": 1,
                                                    "action": "assigned",
                                                    "status": "assigned",
                                                    "previousStatus": null,
                                                    "reason": null,
                                                    "respondedAt": null,
                                                    "at": "2027-07-28T09:00:00+00:00",
                                                    "actorUserId": 12,
                                                    "shift": null
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Worker account, scheduling access or plan is not eligible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Worker account, scheduling access or plan is not eligible."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Assignment or swap not found in your employee scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Assignment or swap not found in your employee scope."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "The shift changed or is no longer open for this action.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The shift changed or is no longer open for this action."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid input, ineligible colleague or duplicate pending request.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Invalid input, ineligible colleague or duplicate pending request."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Use your assignmentId to view dated roster events such as assignment, publication, schedule changes, decline and swap-out. The timeline omits legacy acceptance events.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/shift-assignments/{assignment}/messages": {
            "get": {
                "summary": "Read your shift conversation",
                "tags": [
                    "Shifts"
                ],
                "operationId": "shiftResponseMessages",
                "parameters": [
                    {
                        "name": "assignment",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Returns messages between you and scheduling staff for this assignment, with author, timestamp and mine flag.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "data": [
                                                {
                                                    "id": 1,
                                                    "body": "Which gate should I use?",
                                                    "author": "Ada Worker",
                                                    "mine": true,
                                                    "at": "2027-07-28T09:00:00+00:00"
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Worker account, scheduling access or plan is not eligible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Worker account, scheduling access or plan is not eligible."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Assignment or swap not found in your employee scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Assignment or swap not found in your employee scope."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "The shift changed or is no longer open for this action.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The shift changed or is no longer open for this action."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid input, ineligible colleague or duplicate pending request.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Invalid input, ineligible colleague or duplicate pending request."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Returns messages between you and scheduling staff for this assignment, with author, timestamp and mine flag.",
                "x-generated": true
            },
            "post": {
                "summary": "Message the scheduler",
                "tags": [
                    "Shifts"
                ],
                "operationId": "shiftResponseMessage",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "body": {
                                        "type": "string",
                                        "description": "max: 2000"
                                    }
                                },
                                "required": [
                                    "body"
                                ]
                            },
                            "example": {
                                "body": "Which gate should I use?"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "assignment",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Send body (up to 2000 characters) about your assignment. Returns the updated conversation and notifies the responsible scheduling staff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "data": [
                                                {
                                                    "id": 1,
                                                    "body": "Which gate should I use?",
                                                    "author": "Ada Worker",
                                                    "mine": true,
                                                    "at": "2027-07-28T09:00:00+00:00"
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Worker account, scheduling access or plan is not eligible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Worker account, scheduling access or plan is not eligible."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Assignment or swap not found in your employee scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Assignment or swap not found in your employee scope."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "The shift changed or is no longer open for this action.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The shift changed or is no longer open for this action."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid input, ineligible colleague or duplicate pending request.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Invalid input, ineligible colleague or duplicate pending request."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Send body (up to 2000 characters) about your assignment. Returns the updated conversation and notifies the responsible scheduling staff.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/shift-assignments/{assignment}/swap-options": {
            "get": {
                "summary": "Find eligible swap colleagues",
                "tags": [
                    "Shifts"
                ],
                "operationId": "shiftSwapOptions",
                "parameters": [
                    {
                        "name": "assignment",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Use your upcoming assignmentId. id in each choice is the colleague employee ID within your organisation. Only active coworkers assigned to the same project within your tenant are returned. coverEligible indicates cover availability and offeredShifts lists eligible shifts on that project for a two-way exchange. A shift without a project has no options. No private personnel or pay data is returned.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "data": [
                                                {
                                                    "id": 4,
                                                    "name": "Bayo Worker",
                                                    "coverEligible": true,
                                                    "offeredShifts": [
                                                        {
                                                            "id": 16,
                                                            "title": "Afternoon shift",
                                                            "start": "2027-08-02T12:00:00+00:00",
                                                            "end": "2027-08-02T20:00:00+00:00",
                                                            "project": "Site A"
                                                        }
                                                    ]
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Worker account, scheduling access or plan is not eligible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Worker account, scheduling access or plan is not eligible."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Assignment or swap not found in your employee scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Assignment or swap not found in your employee scope."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "The shift changed or is no longer open for this action.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The shift changed or is no longer open for this action."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid input, ineligible colleague or duplicate pending request.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Invalid input, ineligible colleague or duplicate pending request."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Use your upcoming assignmentId. id in each choice is the colleague employee ID within your organisation. Only active coworkers assigned to the same project within your tenant are returned. coverEligible indicates cover availability and offeredShifts lists eligible shifts on that project for a two-way exchange. A shift without a project has no options. No private personnel or pay data is returned.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/shift-assignments/{assignment}/swaps": {
            "post": {
                "summary": "Request shift cover or an exchange",
                "tags": [
                    "Shifts"
                ],
                "operationId": "shiftSwapMobileStore",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "date": {
                                        "type": "string",
                                        "format": "date"
                                    },
                                    "employeeId": {
                                        "type": "integer"
                                    },
                                    "offeredShiftId": {
                                        "type": "integer",
                                        "nullable": true
                                    },
                                    "reason": {
                                        "type": "string",
                                        "nullable": true,
                                        "description": "max: 1000"
                                    }
                                },
                                "required": [
                                    "date",
                                    "employeeId"
                                ]
                            },
                            "example": {
                                "employeeId": 4,
                                "date": "2027-08-01",
                                "reason": "Family commitment"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "assignment",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Use your assignmentId in the URL. Send employeeId for the colleague, date (YYYY-MM-DD) matching your selected shift start in the organisation timezone, and optional reason. Without offeredShiftId the colleague covers your shift; supply an eligible offeredShifts id from swap-options for a two-way exchange. The server derives your employee and tenant. The colleague must currently belong to the shift project within your tenant, and an offered shift must be on the same project. Supervisor approval is required. The roster updates immediately on approval after project membership and eligibility are rechecked. Duplicate pending requests return 422.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "message": "Swap requested. A supervisor will decide.",
                                            "data": {
                                                "id": 8,
                                                "shiftId": 15,
                                                "requestingEmployeeId": 3,
                                                "employeeId": 4,
                                                "date": "2027-08-01",
                                                "offeredShiftId": null,
                                                "status": "pending",
                                                "reason": "Family commitment",
                                                "rejectionReason": null,
                                                "reviewedBy": null,
                                                "reviewedAt": null,
                                                "submittedAt": "2027-07-28T09:00:00+00:00",
                                                "canWithdraw": true
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Worker account, scheduling access or plan is not eligible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Worker account, scheduling access or plan is not eligible."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Assignment or swap not found in your employee scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Assignment or swap not found in your employee scope."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "The shift changed or is no longer open for this action.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The shift changed or is no longer open for this action."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid input, ineligible colleague or duplicate pending request.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Invalid input, ineligible colleague or duplicate pending request."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Use your assignmentId in the URL. Send employeeId for the colleague, date (YYYY-MM-DD) matching your selected shift start in the organisation timezone, and optional reason. Without offeredShiftId the colleague covers your shift; supply an eligible offeredShifts id from swap-options for a two-way exchange. The server derives your employee and tenant. The colleague must currently belong to the shift project within your tenant, and an offered shift must be on the same project. Supervisor approval is required. The roster updates immediately on approval after project membership and eligibility are rechecked. Duplicate pending requests return 422.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/shift-swaps": {
            "get": {
                "summary": "List your shift swaps",
                "tags": [
                    "Shifts"
                ],
                "operationId": "shiftSwapIndex",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Returns only requests you submitted or are the target of, including status, review decision and canWithdraw. Employee profile and pay fields are excluded. Approval and rejection remain tenant staff actions.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "data": [
                                                {
                                                    "id": 8,
                                                    "shiftId": 15,
                                                    "requestingEmployeeId": 3,
                                                    "employeeId": 4,
                                                    "date": "2027-08-01",
                                                    "offeredShiftId": null,
                                                    "status": "pending",
                                                    "reason": "Family commitment",
                                                    "rejectionReason": null,
                                                    "reviewedBy": null,
                                                    "reviewedAt": null,
                                                    "submittedAt": "2027-07-28T09:00:00+00:00",
                                                    "canWithdraw": true
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Worker account, scheduling access or plan is not eligible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Worker account, scheduling access or plan is not eligible."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Assignment or swap not found in your employee scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Assignment or swap not found in your employee scope."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "The shift changed or is no longer open for this action.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The shift changed or is no longer open for this action."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid input, ineligible colleague or duplicate pending request.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Invalid input, ineligible colleague or duplicate pending request."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Returns only requests you submitted or are the target of, including status, review decision and canWithdraw. Employee profile and pay fields are excluded. Approval and rejection remain tenant staff actions.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/shift-swaps/{swapId}": {
            "delete": {
                "summary": "Withdraw your swap request",
                "tags": [
                    "Shifts"
                ],
                "operationId": "shiftSwapDestroy",
                "parameters": [
                    {
                        "name": "swapId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Only the requesting worker can withdraw a pending request. The target colleague cannot withdraw it. The request and its history are retained with cancelled status.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "message": "Shift swap withdrawn"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Worker account, scheduling access or plan is not eligible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Worker account, scheduling access or plan is not eligible."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Assignment or swap not found in your employee scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Assignment or swap not found in your employee scope."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "The shift changed or is no longer open for this action.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The shift changed or is no longer open for this action."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid input, ineligible colleague or duplicate pending request.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Invalid input, ineligible colleague or duplicate pending request."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Only the requesting worker can withdraw a pending request. The target colleague cannot withdraw it. The request and its history are retained with cancelled status.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/shift-swaps/{swapId}/history": {
            "get": {
                "summary": "View your swap progress",
                "tags": [
                    "Shifts"
                ],
                "operationId": "shiftSwapHistory",
                "parameters": [
                    {
                        "name": "swapId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Returns dated requested, approved, rejected or withdrawn audit events for swaps involving you.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "data": [
                                                {
                                                    "id": 1,
                                                    "action": "requested",
                                                    "actor": "Ada Worker",
                                                    "at": "2027-07-28T09:00:00+00:00",
                                                    "reason": "Family commitment",
                                                    "changes": {
                                                        "action": "requested",
                                                        "swap": {
                                                            "id": 8
                                                        }
                                                    }
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Worker account, scheduling access or plan is not eligible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Worker account, scheduling access or plan is not eligible."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Assignment or swap not found in your employee scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Assignment or swap not found in your employee scope."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "The shift changed or is no longer open for this action.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The shift changed or is no longer open for this action."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid input, ineligible colleague or duplicate pending request.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Invalid input, ineligible colleague or duplicate pending request."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Returns dated requested, approved, rejected or withdrawn audit events for swaps involving you.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/shifts": {
            "get": {
                "summary": "List your assigned shifts",
                "tags": [
                    "Shifts"
                ],
                "operationId": "mobileShiftIndex",
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "description": "min: 1"
                        }
                    },
                    {
                        "name": "scope",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "upcoming",
                                "past"
                            ]
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List your published assignments as soon as they are scheduled. scope=upcoming (default) includes ongoing and future shifts ordered earliest first; scope=past returns ended shifts newest first, including declined and swapped-out history. Paginated 20 per page. id identifies the shift; assignmentId identifies your assignment and is used for all worker actions. Times include UTC offsets; date for swaps uses the organisation timezone.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "assignedShifts": {
                                        "value": {
                                            "status": "success",
                                            "data": [
                                                {
                                                    "id": 15,
                                                    "assignmentId": 21,
                                                    "revision": 1,
                                                    "title": "Morning shift",
                                                    "start_time": "2027-08-01T08:00:00+00:00",
                                                    "end_time": "2027-08-01T16:00:00+00:00",
                                                    "status": "filled",
                                                    "assignment_status": "assigned",
                                                    "project_id": null,
                                                    "crew_id": null
                                                }
                                            ],
                                            "meta": {
                                                "scope": "upcoming",
                                                "declineReasonRequired": false,
                                                "current_page": 1,
                                                "last_page": 1,
                                                "total": 1
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing/invalid credentials or expired bearer token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Unauthenticated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden: worker eligibility, permissions, or password setup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "This action is unauthorized."
                                        }
                                    },
                                    "setupRequired": {
                                        "value": {
                                            "status": "error",
                                            "code": "password_change_required",
                                            "message": "Replace your temporary password to continue."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Record not found in this worker scope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Not Found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed, code invalid/expired/locked, or allowance unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "The given data was invalid.",
                                            "errors": {
                                                "perPage": [
                                                    "The supplied value is invalid."
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit or OTP resend cooldown; retry with backoff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "error": {
                                        "value": {
                                            "message": "Too Many Attempts."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "List your published assignments as soon as they are scheduled. scope=upcoming (default) includes ongoing and future shifts ordered earliest first; scope=past returns ended shifts newest first, including declined and swapped-out history. Paginated 20 per page. id identifies the shift; assignmentId identifies your assignment and is used for all worker actions. Times include UTC offsets; date for swaps uses the organisation timezone.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/timesheets": {
            "get": {
                "summary": "List your timesheet summaries",
                "tags": [
                    "Timesheets"
                ],
                "operationId": "mobileTimesheetIndex",
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        }
                    },
                    {
                        "name": "perPage",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100,
                            "default": 20
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "draft",
                                "submitted",
                                "approved",
                                "rejected"
                            ]
                        }
                    },
                    {
                        "name": "startDate",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "endDate",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Returns only your attendance-generated timesheets, newest period first. Filter by status or overlapping period dates using startDate/endDate (YYYY-MM-DD); paginate with page/perPage (20 by default, maximum 100). meta.summary totals all matching rows, not just the page. Hours are recorded timesheet hours, not proof of payroll payment. No employee selector is accepted or needed.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": [
                                                {
                                                    "id": 5,
                                                    "employeeId": 3,
                                                    "periodStart": "2026-11-09",
                                                    "periodEnd": "2026-11-15",
                                                    "status": "draft",
                                                    "regularHours": 8,
                                                    "overtimeHours": 0,
                                                    "doubleTimeHours": 0,
                                                    "totalHours": 8,
                                                    "submittedAt": null,
                                                    "resubmittedAt": null,
                                                    "approvedAt": null,
                                                    "reviewReason": null,
                                                    "disputedDates": [],
                                                    "locked": false,
                                                    "canSubmit": true,
                                                    "canRequestCorrection": true,
                                                    "timezone": "UTC"
                                                }
                                            ],
                                            "meta": {
                                                "current_page": 1,
                                                "last_page": 1,
                                                "per_page": 20,
                                                "total": 1,
                                                "summary": {
                                                    "regularHours": 8,
                                                    "overtimeHours": 0,
                                                    "doubleTimeHours": 0,
                                                    "totalHours": 8
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Worker bearer token is missing or expired."
                    },
                    "403": {
                        "description": "Inactive worker, wrong tenant, module restriction or permanent-password setup required."
                    },
                    "404": {
                        "description": "Timesheet, attendance entry or assigned shift is outside your employee/tenant/period scope."
                    },
                    "422": {
                        "description": "Invalid fields or clock times, locked/approved/invoiced sheet, invalid submission state or missing-punch eligibility."
                    },
                    "429": {
                        "description": "Rate limited; retry with backoff."
                    }
                },
                "description": "Returns only your attendance-generated timesheets, newest period first. Filter by status or overlapping period dates using startDate/endDate (YYYY-MM-DD); paginate with page/perPage (20 by default, maximum 100). meta.summary totals all matching rows, not just the page. Hours are recorded timesheet hours, not proof of payroll payment. No employee selector is accepted or needed.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/timesheets/{timesheet}": {
            "get": {
                "summary": "View your daily timesheet breakdown",
                "tags": [
                    "Timesheets"
                ],
                "operationId": "mobileTimesheetShow",
                "parameters": [
                    {
                        "name": "timesheet",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "description": "Your timesheet id from the mobile list."
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Use id from your timesheet list. Returns regular, overtime and double-time totals, one day per accounting-period date, attendance sessions and breaks, eligible hours, review progress, disputed dates and pending correction count. timezone identifies the backend accounting timezone used by the timesheet builder. Saved daily work-rule splits are used; a legacy worked day without a saved split returns null allocations instead of an invented overtime calculation. Another worker or tenant returns 404.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": 5,
                                                "employeeId": 3,
                                                "periodStart": "2026-11-09",
                                                "periodEnd": "2026-11-15",
                                                "status": "draft",
                                                "regularHours": 8,
                                                "overtimeHours": 0,
                                                "doubleTimeHours": 0,
                                                "totalHours": 8,
                                                "submittedAt": null,
                                                "resubmittedAt": null,
                                                "approvedAt": null,
                                                "reviewReason": null,
                                                "disputedDates": [],
                                                "locked": false,
                                                "canSubmit": true,
                                                "canRequestCorrection": true,
                                                "timezone": "UTC",
                                                "days": [
                                                    {
                                                        "date": "2026-11-09",
                                                        "regularHours": 8,
                                                        "overtimeHours": 0,
                                                        "doubleTimeHours": 0,
                                                        "recordedHours": 8,
                                                        "eligibleHours": 8,
                                                        "disputed": false,
                                                        "records": [
                                                            {
                                                                "id": 42,
                                                                "employeeId": 3,
                                                                "state": "clocked_out",
                                                                "status": "completed",
                                                                "clockIn": "2026-11-09T08:00:00+00:00",
                                                                "clockOut": "2026-11-09T16:00:00+00:00",
                                                                "totalHours": 8,
                                                                "verificationStatus": "verified",
                                                                "verificationNote": null,
                                                                "isGeofenceException": false,
                                                                "exceptionReason": null,
                                                                "rejectionReason": null,
                                                                "shift": null,
                                                                "project": null,
                                                                "breaks": []
                                                            }
                                                        ]
                                                    },
                                                    {
                                                        "date": "2026-11-10",
                                                        "regularHours": 0,
                                                        "overtimeHours": 0,
                                                        "doubleTimeHours": 0,
                                                        "recordedHours": 0,
                                                        "eligibleHours": 0,
                                                        "disputed": false,
                                                        "records": []
                                                    },
                                                    {
                                                        "date": "2026-11-11",
                                                        "regularHours": 0,
                                                        "overtimeHours": 0,
                                                        "doubleTimeHours": 0,
                                                        "recordedHours": 0,
                                                        "eligibleHours": 0,
                                                        "disputed": false,
                                                        "records": []
                                                    },
                                                    {
                                                        "date": "2026-11-12",
                                                        "regularHours": 0,
                                                        "overtimeHours": 0,
                                                        "doubleTimeHours": 0,
                                                        "recordedHours": 0,
                                                        "eligibleHours": 0,
                                                        "disputed": false,
                                                        "records": []
                                                    },
                                                    {
                                                        "date": "2026-11-13",
                                                        "regularHours": 0,
                                                        "overtimeHours": 0,
                                                        "doubleTimeHours": 0,
                                                        "recordedHours": 0,
                                                        "eligibleHours": 0,
                                                        "disputed": false,
                                                        "records": []
                                                    },
                                                    {
                                                        "date": "2026-11-14",
                                                        "regularHours": 0,
                                                        "overtimeHours": 0,
                                                        "doubleTimeHours": 0,
                                                        "recordedHours": 0,
                                                        "eligibleHours": 0,
                                                        "disputed": false,
                                                        "records": []
                                                    },
                                                    {
                                                        "date": "2026-11-15",
                                                        "regularHours": 0,
                                                        "overtimeHours": 0,
                                                        "doubleTimeHours": 0,
                                                        "recordedHours": 0,
                                                        "eligibleHours": 0,
                                                        "disputed": false,
                                                        "records": []
                                                    }
                                                ],
                                                "overtimeReview": {
                                                    "requiresApproval": false,
                                                    "sourceFingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                                                    "overtimeHours": 0,
                                                    "doubleTimeHours": 0,
                                                    "status": "not_required",
                                                    "requests": []
                                                },
                                                "pendingCorrectionCount": 0,
                                                "progress": []
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Worker bearer token is missing or expired."
                    },
                    "403": {
                        "description": "Inactive worker, wrong tenant, module restriction or permanent-password setup required."
                    },
                    "404": {
                        "description": "Timesheet, attendance entry or assigned shift is outside your employee/tenant/period scope."
                    },
                    "422": {
                        "description": "Invalid fields or clock times, locked/approved/invoiced sheet, invalid submission state or missing-punch eligibility."
                    },
                    "429": {
                        "description": "Rate limited; retry with backoff."
                    }
                },
                "description": "Use id from your timesheet list. Returns regular, overtime and double-time totals, one day per accounting-period date, attendance sessions and breaks, eligible hours, review progress, disputed dates and pending correction count. timezone identifies the backend accounting timezone used by the timesheet builder. Saved daily work-rule splits are used; a legacy worked day without a saved split returns null allocations instead of an invented overtime calculation. Another worker or tenant returns 404.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/timesheets/{timesheet}/corrections": {
            "get": {
                "summary": "Track your timesheet correction requests",
                "tags": [
                    "Timesheets"
                ],
                "operationId": "mobileTimesheetCorrections",
                "parameters": [
                    {
                        "name": "timesheet",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "description": "Your timesheet id from the mobile list."
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        }
                    },
                    {
                        "name": "perPage",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100,
                            "default": 20
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated correction proposals for your timesheet and its attendance entries. Returns proposed clock times, pending/approved/rejected status, original reason, and decision date, reviewer name and decision message when decided. Requests remain visible in the tenant time-review workflow. No payroll or private employee model is exposed.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": [
                                                {
                                                    "id": 12,
                                                    "kind": "correction",
                                                    "body": "Clock-out was recorded early",
                                                    "author": "Ada Worker",
                                                    "mine": true,
                                                    "at": "2026-11-10T18:00:00+00:00",
                                                    "proposedClockIn": null,
                                                    "proposedClockOut": "2026-11-09T17:00:00+00:00",
                                                    "timesheetId": 5,
                                                    "correctionStatus": "pending",
                                                    "attachment": null,
                                                    "decidesMessageId": null,
                                                    "attendanceId": 42,
                                                    "shiftId": 9,
                                                    "decision": null
                                                }
                                            ],
                                            "meta": {
                                                "current_page": 1,
                                                "last_page": 1,
                                                "per_page": 20,
                                                "total": 1
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Worker bearer token is missing or expired."
                    },
                    "403": {
                        "description": "Inactive worker, wrong tenant, module restriction or permanent-password setup required."
                    },
                    "404": {
                        "description": "Timesheet, attendance entry or assigned shift is outside your employee/tenant/period scope."
                    },
                    "422": {
                        "description": "Invalid fields or clock times, locked/approved/invoiced sheet, invalid submission state or missing-punch eligibility."
                    },
                    "429": {
                        "description": "Rate limited; retry with backoff."
                    }
                },
                "description": "Paginated correction proposals for your timesheet and its attendance entries. Returns proposed clock times, pending/approved/rejected status, original reason, and decision date, reviewer name and decision message when decided. Requests remain visible in the tenant time-review workflow. No payroll or private employee model is exposed.",
                "x-generated": true
            },
            "post": {
                "summary": "Request a time correction or a missing punch",
                "tags": [
                    "Timesheets"
                ],
                "operationId": "mobileTimesheetStoreCorrection",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "attendanceId": {
                                        "type": "integer",
                                        "minimum": 1
                                    },
                                    "shiftId": {
                                        "type": "integer",
                                        "minimum": 1
                                    },
                                    "proposedClockIn": {
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "proposedClockOut": {
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "reason": {
                                        "type": "string",
                                        "maxLength": 2000
                                    }
                                },
                                "required": [
                                    "reason"
                                ],
                                "oneOf": [
                                    {
                                        "required": [
                                            "attendanceId"
                                        ],
                                        "not": {
                                            "required": [
                                                "shiftId"
                                            ]
                                        },
                                        "anyOf": [
                                            {
                                                "required": [
                                                    "proposedClockIn"
                                                ]
                                            },
                                            {
                                                "required": [
                                                    "proposedClockOut"
                                                ]
                                            }
                                        ]
                                    },
                                    {
                                        "required": [
                                            "shiftId",
                                            "proposedClockIn",
                                            "proposedClockOut"
                                        ],
                                        "not": {
                                            "required": [
                                                "attendanceId"
                                            ]
                                        }
                                    }
                                ]
                            },
                            "examples": {
                                "existingEntry": {
                                    "value": {
                                        "attendanceId": 42,
                                        "proposedClockOut": "2026-11-09T17:00:00+00:00",
                                        "reason": "Clock-out was recorded early"
                                    }
                                },
                                "missingPunch": {
                                    "value": {
                                        "shiftId": 9,
                                        "proposedClockIn": "2026-11-09T08:00:00Z",
                                        "proposedClockOut": "2026-11-09T16:00:00Z",
                                        "reason": "Missed clocking in"
                                    }
                                }
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "timesheet",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "description": "Your timesheet id from the mobile list."
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Send reason and either attendanceId for your entry in this period or shiftId for your assigned published shift when a punch is missing. Existing-entry corrections need at least one proposedClockIn/proposedClockOut; omitted times remain unchanged at approval. Corrected times must include all recorded breaks; end open breaks first. These checks run again when the reviewer approves. Missing-punch requests need both. Use ISO 8601 timestamps with explicit Z or timezone offset. Clock-out must follow clock-in, be in the past, and be within 24 hours; clock-in must fall in this timesheet. Approved or invoiced timesheets are locked. The worker cannot decide the request: an authorised separate reviewer uses the existing time-messages/{message}/decide endpoint. Approval applies attendance changes and rebuilds totals; rejection leaves hours unchanged. Both sides receive existing attendance.message notifications. Identical pending requests replay with 200; a different pending correction for the same entry/shift returns 409. No files or direct hour totals are accepted.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": 12,
                                                "kind": "correction",
                                                "body": "Clock-out was recorded early",
                                                "author": "Ada Worker",
                                                "mine": true,
                                                "at": "2026-11-10T18:00:00+00:00",
                                                "proposedClockIn": null,
                                                "proposedClockOut": "2026-11-09T17:00:00+00:00",
                                                "timesheetId": 5,
                                                "correctionStatus": "pending",
                                                "attachment": null,
                                                "decidesMessageId": null,
                                                "attendanceId": 42,
                                                "shiftId": 9
                                            },
                                            "replayed": false
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Worker bearer token is missing or expired."
                    },
                    "403": {
                        "description": "Inactive worker, wrong tenant, module restriction or permanent-password setup required."
                    },
                    "404": {
                        "description": "Timesheet, attendance entry or assigned shift is outside your employee/tenant/period scope."
                    },
                    "422": {
                        "description": "Invalid fields or clock times, locked/approved/invoiced sheet, invalid submission state or missing-punch eligibility."
                    },
                    "429": {
                        "description": "Rate limited; retry with backoff."
                    },
                    "200": {
                        "description": "Identical pending correction replayed.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": 12,
                                                "kind": "correction",
                                                "body": "Clock-out was recorded early",
                                                "author": "Ada Worker",
                                                "mine": true,
                                                "at": "2026-11-10T18:00:00+00:00",
                                                "proposedClockIn": null,
                                                "proposedClockOut": "2026-11-09T17:00:00+00:00",
                                                "timesheetId": 5,
                                                "correctionStatus": "pending",
                                                "attachment": null,
                                                "decidesMessageId": null,
                                                "attendanceId": 42,
                                                "shiftId": 9
                                            },
                                            "replayed": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "A different correction for this entry or shift is awaiting review."
                    }
                },
                "description": "Send reason and either attendanceId for your entry in this period or shiftId for your assigned published shift when a punch is missing. Existing-entry corrections need at least one proposedClockIn/proposedClockOut; omitted times remain unchanged at approval. Corrected times must include all recorded breaks; end open breaks first. These checks run again when the reviewer approves. Missing-punch requests need both. Use ISO 8601 timestamps with explicit Z or timezone offset. Clock-out must follow clock-in, be in the past, and be within 24 hours; clock-in must fall in this timesheet. Approved or invoiced timesheets are locked. The worker cannot decide the request: an authorised separate reviewer uses the existing time-messages/{message}/decide endpoint. Approval applies attendance changes and rebuilds totals; rejection leaves hours unchanged. Both sides receive existing attendance.message notifications. Identical pending requests replay with 200; a different pending correction for the same entry/shift returns 409. No files or direct hour totals are accepted.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/timesheets/{timesheet}/overtime-requests": {
            "post": {
                "summary": "Request separate overtime approval for your timesheet",
                "tags": [
                    "Timesheets"
                ],
                "operationId": "mobileTimesheetRequestOvertime",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "reason": {
                                        "type": "string",
                                        "maxLength": 2000
                                    },
                                    "sourceFingerprint": {
                                        "type": "string",
                                        "minLength": 64,
                                        "maxLength": 64
                                    }
                                },
                                "required": [
                                    "reason",
                                    "sourceFingerprint"
                                ]
                            },
                            "example": {
                                "reason": "Stayed to finish site work.",
                                "sourceFingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "timesheet",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        }
                    },
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "minLength": 16,
                            "maxLength": 120
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Attendance-backed overtime; hours and compensation are derived from your verified timesheet.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "17",
                                                "code": "OT-01JTESTEXAMPLE",
                                                "employeeId": 3,
                                                "timesheetId": 12,
                                                "hours": 2,
                                                "payRate": 20,
                                                "cost": 60,
                                                "status": "Pending",
                                                "attendanceSnapshot": {
                                                    "timesheetId": 12,
                                                    "sourceFingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                                                    "hours": 2,
                                                    "overtimeHours": 2,
                                                    "doubleTimeHours": 0,
                                                    "payRate": 20,
                                                    "currency": "NGN",
                                                    "cost": 60
                                                },
                                                "reviewedBy": null,
                                                "reviewedAt": null,
                                                "reviewReason": null
                                            },
                                            "replayed": false
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired bearer token."
                    },
                    "403": {
                        "description": "Your role cannot perform this timesheet action."
                    },
                    "404": {
                        "description": "Timesheet or request is outside your employee/tenant scope."
                    },
                    "409": {
                        "description": "Changed sourceFingerprint, reused key with different details, or an existing active request for these hours."
                    },
                    "422": {
                        "description": "Invalid input, client-supplied identity/hours/rates, no separate approval required, incomplete compensation, or financially allocated time."
                    },
                    "200": {
                        "description": "Exact request replayed without another submission.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "replayed": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "17",
                                                "code": "OT-01JTESTEXAMPLE",
                                                "employeeId": 3,
                                                "timesheetId": 12,
                                                "hours": 2,
                                                "payRate": 20,
                                                "cost": 60,
                                                "status": "Pending",
                                                "attendanceSnapshot": {
                                                    "timesheetId": 12,
                                                    "sourceFingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                                                    "hours": 2,
                                                    "overtimeHours": 2,
                                                    "doubleTimeHours": 0,
                                                    "payRate": 20,
                                                    "currency": "NGN",
                                                    "cost": 60
                                                },
                                                "reviewedBy": null,
                                                "reviewedAt": null,
                                                "reviewReason": null
                                            },
                                            "replayed": true
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "description": "Send reason and sourceFingerprint from overtimeReview in your timesheet detail. Idempotency-Key is required; replay the same key and payload after an uncertain response. Identity, hours, rates, currency, cost and applicable policy come from your verified attendance timesheet. Returns 409 for changed source figures or an existing active request. Available only when the saved work rule requires separate overtime approval; otherwise use normal timesheet submission.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/timesheets/{timesheet}/overtime-requests/{overtimeRequest}/cancel": {
            "post": {
                "summary": "Cancel your pending overtime request",
                "tags": [
                    "Timesheets"
                ],
                "operationId": "mobileTimesheetCancelOvertime",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "reason": {
                                        "type": "string",
                                        "maxLength": 2000
                                    }
                                }
                            },
                            "example": {
                                "reason": "Submitted in error."
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "timesheet",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        }
                    },
                    {
                        "name": "overtimeRequest",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        }
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Attendance-backed overtime; hours and compensation are derived from your verified timesheet.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": "17",
                                                "code": "OT-01JTESTEXAMPLE",
                                                "employeeId": 3,
                                                "timesheetId": 12,
                                                "hours": 2,
                                                "payRate": 20,
                                                "cost": 60,
                                                "status": "Cancelled",
                                                "attendanceSnapshot": {
                                                    "timesheetId": 12,
                                                    "sourceFingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                                                    "hours": 2,
                                                    "overtimeHours": 2,
                                                    "doubleTimeHours": 0,
                                                    "payRate": 20,
                                                    "currency": "NGN",
                                                    "cost": 60
                                                },
                                                "reviewedBy": 12,
                                                "reviewedAt": "2026-11-10T18:30:00+00:00",
                                                "reviewReason": "Submitted in error."
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or expired bearer token."
                    },
                    "403": {
                        "description": "Your role cannot perform this timesheet action."
                    },
                    "404": {
                        "description": "Timesheet or request is outside your employee/tenant scope."
                    },
                    "409": {
                        "description": "Changed sourceFingerprint, reused key with different details, or an existing active request for these hours."
                    },
                    "422": {
                        "description": "Invalid input, client-supplied identity/hours/rates, no separate approval required, incomplete compensation, or financially allocated time."
                    }
                },
                "description": "The timesheet and request must both belong to your authenticated employee. Cancels only a pending request and preserves its snapshot and review history. Exact cancellation retries return the existing cancelled request. Approved requests cannot be cancelled.",
                "x-generated": true
            }
        },
        "/api/v1/mobile/timesheets/{timesheet}/submit": {
            "post": {
                "summary": "Submit your timesheet for review",
                "tags": [
                    "Timesheets"
                ],
                "operationId": "mobileTimesheetSubmit",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "note": {
                                        "type": "string",
                                        "maxLength": 1000
                                    }
                                }
                            },
                            "example": {
                                "note": "Please review my hours"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "timesheet",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "description": "Your timesheet id from the mobile list."
                    }
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Send optional note, up to 1000 characters. Only your draft or rejected, uninvoiced timesheets can be submitted. Rejections require resubmission before approval. Tenant payroll auto-approval applies only when existing workflow, dispute and correction rules permit it. Reviewers receive an in-app notification, or the worker receives an automatic approval notification. A repeated submit after status changes returns 422; refresh detail after an uncertain response. Workers cannot supply totals or approval status.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "examples": {
                                    "result": {
                                        "value": {
                                            "status": "success",
                                            "data": {
                                                "id": 5,
                                                "employeeId": 3,
                                                "periodStart": "2026-11-09",
                                                "periodEnd": "2026-11-15",
                                                "status": "submitted",
                                                "regularHours": 8,
                                                "overtimeHours": 0,
                                                "doubleTimeHours": 0,
                                                "totalHours": 8,
                                                "submittedAt": "2026-11-10T18:00:00+00:00",
                                                "resubmittedAt": null,
                                                "approvedAt": null,
                                                "reviewReason": null,
                                                "disputedDates": [],
                                                "locked": false,
                                                "canSubmit": false,
                                                "canRequestCorrection": true,
                                                "timezone": "UTC",
                                                "days": [
                                                    {
                                                        "date": "2026-11-09",
                                                        "regularHours": 8,
                                                        "overtimeHours": 0,
                                                        "doubleTimeHours": 0,
                                                        "recordedHours": 8,
                                                        "eligibleHours": 8,
                                                        "disputed": false,
                                                        "records": [
                                                            {
                                                                "id": 42,
                                                                "employeeId": 3,
                                                                "state": "clocked_out",
                                                                "status": "completed",
                                                                "clockIn": "2026-11-09T08:00:00+00:00",
                                                                "clockOut": "2026-11-09T16:00:00+00:00",
                                                                "totalHours": 8,
                                                                "verificationStatus": "verified",
                                                                "verificationNote": null,
                                                                "isGeofenceException": false,
                                                                "exceptionReason": null,
                                                                "rejectionReason": null,
                                                                "shift": null,
                                                                "project": null,
                                                                "breaks": []
                                                            }
                                                        ]
                                                    },
                                                    {
                                                        "date": "2026-11-10",
                                                        "regularHours": 0,
                                                        "overtimeHours": 0,
                                                        "doubleTimeHours": 0,
                                                        "recordedHours": 0,
                                                        "eligibleHours": 0,
                                                        "disputed": false,
                                                        "records": []
                                                    },
                                                    {
                                                        "date": "2026-11-11",
                                                        "regularHours": 0,
                                                        "overtimeHours": 0,
                                                        "doubleTimeHours": 0,
                                                        "recordedHours": 0,
                                                        "eligibleHours": 0,
                                                        "disputed": false,
                                                        "records": []
                                                    },
                                                    {
                                                        "date": "2026-11-12",
                                                        "regularHours": 0,
                                                        "overtimeHours": 0,
                                                        "doubleTimeHours": 0,
                                                        "recordedHours": 0,
                                                        "eligibleHours": 0,
                                                        "disputed": false,
                                                        "records": []
                                                    },
                                                    {
                                                        "date": "2026-11-13",
                                                        "regularHours": 0,
                                                        "overtimeHours": 0,
                                                        "doubleTimeHours": 0,
                                                        "recordedHours": 0,
                                                        "eligibleHours": 0,
                                                        "disputed": false,
                                                        "records": []
                                                    },
                                                    {
                                                        "date": "2026-11-14",
                                                        "regularHours": 0,
                                                        "overtimeHours": 0,
                                                        "doubleTimeHours": 0,
                                                        "recordedHours": 0,
                                                        "eligibleHours": 0,
                                                        "disputed": false,
                                                        "records": []
                                                    },
                                                    {
                                                        "date": "2026-11-15",
                                                        "regularHours": 0,
                                                        "overtimeHours": 0,
                                                        "doubleTimeHours": 0,
                                                        "recordedHours": 0,
                                                        "eligibleHours": 0,
                                                        "disputed": false,
                                                        "records": []
                                                    }
                                                ],
                                                "overtimeReview": {
                                                    "requiresApproval": false,
                                                    "sourceFingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                                                    "overtimeHours": 0,
                                                    "doubleTimeHours": 0,
                                                    "status": "not_required",
                                                    "requests": []
                                                },
                                                "pendingCorrectionCount": 0,
                                                "progress": [
                                                    {
                                                        "stage": "submitted",
                                                        "date": "2026-11-10T18:00:00+00:00",
                                                        "actorName": "Ada Worker",
                                                        "reason": "Please review my hours"
                                                    }
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Worker bearer token is missing or expired."
                    },
                    "403": {
                        "description": "Inactive worker, wrong tenant, module restriction or permanent-password setup required."
                    },
                    "404": {
                        "description": "Timesheet, attendance entry or assigned shift is outside your employee/tenant/period scope."
                    },
                    "422": {
                        "description": "Invalid fields or clock times, locked/approved/invoiced sheet, invalid submission state or missing-punch eligibility."
                    },
                    "429": {
                        "description": "Rate limited; retry with backoff."
                    }
                },
                "description": "Send optional note, up to 1000 characters. Only your draft or rejected, uninvoiced timesheets can be submitted. Rejections require resubmission before approval. Tenant payroll auto-approval applies only when existing workflow, dispute and correction rules permit it. Reviewers receive an in-app notification, or the worker receives an automatic approval notification. A repeated submit after status changes returns 422; refresh detail after an uncertain response. Workers cannot supply totals or approval status.",
                "x-generated": true
            }
        }
    },
    "servers": [
        {
            "url": "/",
            "description": "Current API server"
        }
    ],
    "tags": [
        {
            "name": "Login"
        },
        {
            "name": "Passwords"
        },
        {
            "name": "Profile"
        },
        {
            "name": "Leave"
        },
        {
            "name": "Shifts"
        },
        {
            "name": "Attendance"
        },
        {
            "name": "Timesheets"
        },
        {
            "name": "Notifications"
        },
        {
            "name": "Documents"
        },
        {
            "name": "Certificates"
        },
        {
            "name": "Incidents"
        },
        {
            "name": "Daily Progress"
        },
        {
            "name": "Expenses"
        }
    ],
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "description": "Worker bearer token; use the restricted token only during first password setup."
            }
        }
    }
}
