@serviceai/api-spec 1.2.417 → 1.2.419

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "ServiceAi API",
-    "version": "1.2.417",
+    "version": "1.2.419",
     "description": "Source-of-truth API contract for ServiceAi. Generated from `shared/schema.ts` Zod schemas by `scripts/build-api-spec.ts`. Versioning policy: see `docs/api-versioning.md`. The hand-written docs/ios-contract.md and docs/lidar-mobile-upload-contract.md are human-readable design notes only — this spec is the canonical wire contract.",
     "license": {
       "name": "Proprietary",
@@ -59,6 +59,10 @@
     {
       "name": "schedule",
       "description": "When a person is expected to work (employee_shifts), and time-off requests against it. Separate from the job calendar by design."
+    },
+    {
+      "name": "account",
+      "description": "The signed-in person's own account: asking for it to be deleted."
     }
   ],
   "components": {
@@ -122,7 +126,7 @@
         "properties": {
           "apiVersion": {
             "type": "string",
-            "example": "1.2.417"
+            "example": "1.2.419"
           },
           "minClientVersion": {
             "type": "string",
@@ -3182,6 +3186,80 @@
           "sdp"
         ]
       },
+      "PunchTimeCheck": {
+        "type": "object",
+        "properties": {
+          "reasons": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "server_time",
+                "unverified",
+                "clock_changed",
+                "too_old",
+                "replaced_auto_close",
+                "after_auto_close",
+                "auto_close_kept"
+              ]
+            },
+            "description": "server_time: the phone's time was more than 2 minutes from the server's, and the server's was recorded. unverified: the phone restarted before sending, so the time couldn't be checked; the phone's was kept. clock_changed: the phone's clock was changed by hand. Late stops (T6): too_old: a stop more than 12 hours old that couldn't be proven was recorded at the 12-hour limit. replaced_auto_close: a proven stop replaced the automatic close (autoAt). after_auto_close: a stop later than the automatic close; the automatic close was kept. auto_close_kept: a stop earlier than the automatic close that wasn't applied (keptBecause)."
+          },
+          "phoneAt": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "format": "date-time",
+            "description": "The phone's own time for the tap."
+          },
+          "serverAt": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "format": "date-time",
+            "description": "The tap by the server's clock (arrival minus tapElapsedMs); null when the phone couldn't say."
+          },
+          "receivedAt": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the request reached the server."
+          },
+          "tapElapsedMs": {
+            "type": [
+              "integer",
+              "null"
+            ]
+          },
+          "verified": {
+            "type": "boolean",
+            "description": "True when the phone's stopwatch proved the tap's time."
+          },
+          "autoAt": {
+            "type": "string",
+            "format": "date-time",
+            "description": "The automatic close a late stop replaced or was held against."
+          },
+          "keptBecause": {
+            "type": "string",
+            "enum": [
+              "unverified",
+              "office",
+              "locked"
+            ],
+            "description": "Why a late stop wasn't applied: its time couldn't be proven, the office had already changed or approved the time, or the pay period is locked."
+          }
+        },
+        "required": [
+          "reasons",
+          "phoneAt",
+          "serverAt",
+          "receivedAt",
+          "tapElapsedMs"
+        ],
+        "description": "A tap whose time the office is asked to look at, with both times. It waits in Team › Needs attention."
+      },
       "TimeEntry": {
         "type": "object",
         "properties": {
@@ -3317,6 +3395,64 @@
             "type": "integer",
             "description": "Unpaid break minutes recorded against this entry."
           },
+          "startCheck": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "enum": [
+              "away",
+              "no_location"
+            ],
+            "description": "Job time started by hand away from the job ('away') or with no usable location ('no_location'); null for a normal start. The office decides it."
+          },
+          "startDistanceM": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "description": "How far from the job's site center the start was, when startCheck is 'away'."
+          },
+          "startReview": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "enum": [
+              "approved",
+              "not_approved",
+              "moved"
+            ],
+            "description": "The office's decision on a flagged start; null while it waits. 'not_approved' stays on the timesheet but off the job's costing."
+          },
+          "clockInCheck": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/PunchTimeCheck"
+              },
+              {
+                "type": [
+                  "object",
+                  "null"
+                ],
+                "description": "Set when the start's time was checked and the office is asked to look; clockIn holds the time recorded."
+              }
+            ]
+          },
+          "clockOutCheck": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/PunchTimeCheck"
+              },
+              {
+                "type": [
+                  "object",
+                  "null"
+                ],
+                "description": "The same for the stop; clockOut holds the time recorded."
+              }
+            ]
+          },
           "createdAt": {
             "type": [
               "string",
@@ -3330,7 +3466,7 @@
           },
           "userName": {
             "type": "string",
-            "description": "Enrichment on /entries and /active?scope=team."
+            "description": "Enrichment on /entries."
           }
         },
         "required": [
@@ -3536,6 +3672,34 @@
               "null"
             ]
           },
+          "clockInCheck": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/PunchTimeCheck"
+              },
+              {
+                "type": [
+                  "object",
+                  "null"
+                ],
+                "description": "Set when the Clock In tap's time was checked and the office is asked to look; clockIn holds the time recorded."
+              }
+            ]
+          },
+          "clockOutCheck": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/PunchTimeCheck"
+              },
+              {
+                "type": [
+                  "object",
+                  "null"
+                ],
+                "description": "The same for the Clock Out tap; clockOut holds the time recorded."
+              }
+            ]
+          },
           "editedBy": {
             "type": [
               "string",
@@ -3660,6 +3824,32 @@
       "MyDayResponse": {
         "type": "object",
         "properties": {
+          "payrollAddon": {
+            "type": "boolean",
+            "description": "The company's time tracking (payroll) add-on. False: no Clock In/Out, no work days, schedules, time cards or pay; job time still runs. Then open is null, today is empty, shiftEnd is null, payroll.breakButton and locationTrail are false, and the payroll routes answer 403 PAYROLL_OFF. Not the same as payroll.enabled."
+          },
+          "payroll": {
+            "type": "object",
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "description": "A pay period is set (the company's pay rules are on)."
+              },
+              "breakButton": {
+                "type": "boolean",
+                "description": "Show the break button (false when this person's lunch comes off automatically)."
+              },
+              "breaksPaid": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "enabled",
+              "breakButton",
+              "breaksPaid"
+            ],
+            "description": "The company's pay rules as they touch this person."
+          },
           "dayModel": {
             "type": "boolean",
             "description": "True once this person is on the day model."
@@ -3745,6 +3935,8 @@
           }
         },
         "required": [
+          "payrollAddon",
+          "payroll",
           "dayModel",
           "open",
           "today",
@@ -3935,6 +4127,28 @@
           "autoClockEnabled": {
             "type": "boolean",
             "description": "The user's auto-clock toggle at crossing time. False → the crossing is logged but never acted on."
+          },
+          "tapElapsedMs": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "minimum": 0,
+            "description": "Milliseconds from the tap to this send, from the phone's monotonic clock (a stopwatch the person can't change). An offline replay sends the time since the tap. The server's tap time is its own clock when the request arrives minus this. Within 2 minutes of the phone's time, the phone's time stands (never later than the tap); further apart, the server's tap time is recorded and the office is asked to look. A Clock Out or job time stop it proves this way keeps its real time however old; without it, a stop older than 12 hours is recorded at the 12-hour limit and flagged (T6). Send it with every queued tap, clock-outs included."
+          },
+          "tapTimeUnverified": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "True when the phone restarted between the tap and this send, so there is no stopwatch reading (send no tapElapsedMs). A tap more than 2 minutes old keeps the phone's time and is flagged for the office."
+          },
+          "deviceClockChanged": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "True when the phone's clock was changed by hand since the phone last synced. The tap is flagged for the office."
           }
         },
         "required": [
@@ -3942,7 +4156,7 @@
           "kind",
           "occurredAt"
         ],
-        "description": "One fence crossing as the device saw it."
+        "description": "One fence crossing as the device saw it. With tapElapsedMs (the time since the crossing), the server checks occurredAt against its own clock before the resolver uses it, and the entry the crossing opens or closes carries the check. A departure it proves isn't held to the 12-hour limit (T6)."
       },
       "CrossingsAck": {
         "type": "object",
@@ -4140,6 +4354,10 @@
           "canEdit": {
             "type": "boolean",
             "description": "True only for the primary account."
+          },
+          "jobSiteTracking": {
+            "type": "boolean",
+            "description": "The caller's own switch, set by the office (owner's O9). False: watch no job-site fences and use no location for job time; job time comes only from Start/Stop job time. The office fence, Clock In/Out and the company switches are unaffected. Absent (an older server): treat as true."
           }
         },
         "required": [
@@ -4377,6 +4595,10 @@
             "format": "date",
             "description": "The org-local date, which is not necessarily the device's."
           },
+          "payrollAddon": {
+            "type": "boolean",
+            "description": "False when the company has the time tracking add-on off: no shifts, hours or time off come back, and nothing covers now."
+          },
           "hours": {
             "type": "object",
             "additionalProperties": {
@@ -4488,6 +4710,7 @@
           "from",
           "to",
           "today",
+          "payrollAddon",
           "hours",
           "attendance",
           "shifts",
@@ -4495,6 +4718,82 @@
           "recentTimeOff"
         ],
         "description": "When I should be in, plus what I actually worked. The clock-in expectation lives here."
+      },
+      "OnTheClockRow": {
+        "type": "object",
+        "properties": {
+          "userId": {
+            "type": "string"
+          },
+          "userName": {
+            "type": "string"
+          },
+          "entryId": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "description": "The open site entry; null between sites (a day with nothing open)."
+          },
+          "jobId": {
+            "type": [
+              "integer",
+              "null"
+            ]
+          },
+          "siteType": {
+            "type": "string",
+            "enum": [
+              "job",
+              "office",
+              "none"
+            ],
+            "description": "'none' between sites."
+          },
+          "jobName": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "since": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the work day began, else when the entry did."
+          }
+        },
+        "required": [
+          "userId",
+          "userName",
+          "entryId",
+          "jobId",
+          "siteType",
+          "jobName",
+          "since"
+        ],
+        "description": "One person on the clock (server/onTheClock.ts). Job time with no paid day behind it is left out: that person is at a job, not on the clock."
+      },
+      "AccountDeletionRequest": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "pending",
+              "completed",
+              "cancelled"
+            ]
+          },
+          "requestedAt": {
+            "type": "string",
+            "format": "date-time"
+          }
+        },
+        "required": [
+          "status",
+          "requestedAt"
+        ],
+        "description": "The signed-in person's request to have their account deleted. pending: waiting for the company; completed: the company marked it done; cancelled: the company cancelled it (asking again starts a new one)."
       }
     },
     "parameters": {}
@@ -6490,6 +6789,25 @@
                                     "auto",
                                     "manual"
                                   ]
+                                },
+                                "duplicateOf": {
+                                  "type": "object",
+                                  "properties": {
+                                    "roomId": {
+                                      "type": "integer",
+                                      "description": "Id of the room whose copy of this doorway is drawn."
+                                    },
+                                    "doorIndex": {
+                                      "type": "integer",
+                                      "minimum": 0,
+                                      "description": "Index into that room's `doors[]`."
+                                    }
+                                  },
+                                  "required": [
+                                    "roomId",
+                                    "doorIndex"
+                                  ],
+                                  "description": "Present only on the later-scanned room's copy of a doorway two rooms in this response share (the rooms are linked by a door link, or their doors coincide on one wall). Skip this door's glyph and keep its wall gap; the door it names is the one to draw. Absent on every other door. Read-time only: never send it back, it is never stored."
                                 }
                               },
                               "required": [
@@ -6498,7 +6816,7 @@
                                 "height"
                               ]
                             },
-                            "description": "RoomPlan-classified doors. Distinct from `windows[]` and `openings[]`; append-room `entryDoorwayId` tokens of the form `…-door-<idx>` resolve into THIS array only."
+                            "description": "RoomPlan-classified doors. Distinct from `windows[]` and `openings[]`; append-room `entryDoorwayId` tokens of the form `…-door-<idx>` resolve into THIS array only. A door carrying `duplicateOf` is the hidden copy of a shared doorway (one door per doorway, from the room scanned first)."
                           },
                           "windows": {
                             "type": "array",
@@ -6860,6 +7178,25 @@
                                         "auto",
                                         "manual"
                                       ]
+                                    },
+                                    "duplicateOf": {
+                                      "type": "object",
+                                      "properties": {
+                                        "roomId": {
+                                          "type": "integer",
+                                          "description": "Id of the room whose copy of this doorway is drawn."
+                                        },
+                                        "doorIndex": {
+                                          "type": "integer",
+                                          "minimum": 0,
+                                          "description": "Index into that room's `doors[]`."
+                                        }
+                                      },
+                                      "required": [
+                                        "roomId",
+                                        "doorIndex"
+                                      ],
+                                      "description": "Present only on the later-scanned room's copy of a doorway two rooms in this response share (the rooms are linked by a door link, or their doors coincide on one wall). Skip this door's glyph and keep its wall gap; the door it names is the one to draw. Absent on every other door. Read-time only: never send it back, it is never stored."
                                     }
                                   },
                                   "required": [
@@ -6868,7 +7205,7 @@
                                     "height"
                                   ]
                                 },
-                                "description": "RoomPlan-classified doors. Distinct from `windows[]` and `openings[]`; append-room `entryDoorwayId` tokens of the form `…-door-<idx>` resolve into THIS array only."
+                                "description": "RoomPlan-classified doors. Distinct from `windows[]` and `openings[]`; append-room `entryDoorwayId` tokens of the form `…-door-<idx>` resolve into THIS array only. A door carrying `duplicateOf` is the hidden copy of a shared doorway (one door per doorway, from the room scanned first)."
                               },
                               "windows": {
                                 "type": "array",
@@ -7985,7 +8322,29 @@
                       "null"
                     ],
                     "format": "date-time",
-                    "description": "When the tap happened. The server clamps it."
+                    "description": "When the tap happened, by the phone's clock. The server checks it against its own (tapElapsedMs) and clamps it. From the web (device 'web') it is ignored: the server's receipt time is used."
+                  },
+                  "tapElapsedMs": {
+                    "type": [
+                      "integer",
+                      "null"
+                    ],
+                    "minimum": 0,
+                    "description": "Milliseconds from the tap to this send, from the phone's monotonic clock (a stopwatch the person can't change). An offline replay sends the time since the tap. The server's tap time is its own clock when the request arrives minus this. Within 2 minutes of the phone's time, the phone's time stands (never later than the tap); further apart, the server's tap time is recorded and the office is asked to look. A Clock Out or job time stop it proves this way keeps its real time however old; without it, a stop older than 12 hours is recorded at the 12-hour limit and flagged (T6). Send it with every queued tap, clock-outs included."
+                  },
+                  "tapTimeUnverified": {
+                    "type": [
+                      "boolean",
+                      "null"
+                    ],
+                    "description": "True when the phone restarted between the tap and this send, so there is no stopwatch reading (send no tapElapsedMs). A tap more than 2 minutes old keeps the phone's time and is flagged for the office."
+                  },
+                  "deviceClockChanged": {
+                    "type": [
+                      "boolean",
+                      "null"
+                    ],
+                    "description": "True when the phone's clock was changed by hand since the phone last synced. The tap is flagged for the office."
                   },
                   "notes": {
                     "type": [
@@ -8031,7 +8390,7 @@
             }
           },
           "403": {
-            "description": "Time tracking access denied, or no organization on the session.",
+            "description": "Time tracking access denied, no organization on the session, or code PAYROLL_OFF: the company has the time tracking add-on off (GET /api/time-tracking/day says payrollAddon: false). Don't retry; hide Clock In/Out and the other payroll controls.",
             "content": {
               "application/json": {
                 "schema": {
@@ -8094,7 +8453,7 @@
     },
     "/api/time-tracking/day/clock-out": {
       "post": {
-        "summary": "End my day. Closes every open entry with it.",
+        "summary": "End my day: the paid day only. Job time (fence or job timer) runs until it is stopped or the phone reports leaving, and is never paid past Clock Out.",
         "tags": [
           "time-tracking"
         ],
@@ -8120,6 +8479,7 @@
             "description": "Send `1` to declare this client understands work days. The first request carrying it moves the caller onto the day model permanently (users.time_clock_day_model_since); from then on their fence arrivals only open entries inside an open day."
           }
         ],
+        "description": "A late Clock Out (T6): with tapElapsedMs proving its time, it keeps its real time however old. When the safety net already closed the day (the automatic close), a proven Clock Out earlier than that close replaces it (replacedAutoClose, flagged for the office); anything else about that day is flagged for the office and changes nothing. A proven Clock Out from before the running day started never ends the running day.",
         "requestBody": {
           "content": {
             "application/json": {
@@ -8166,7 +8526,29 @@
                       "null"
                     ],
                     "format": "date-time",
-                    "description": "When the tap happened. The server clamps it."
+                    "description": "When the tap happened, by the phone's clock. The server checks it against its own (tapElapsedMs) and clamps it. From the web (device 'web') it is ignored: the server's receipt time is used."
+                  },
+                  "tapElapsedMs": {
+                    "type": [
+                      "integer",
+                      "null"
+                    ],
+                    "minimum": 0,
+                    "description": "Milliseconds from the tap to this send, from the phone's monotonic clock (a stopwatch the person can't change). An offline replay sends the time since the tap. The server's tap time is its own clock when the request arrives minus this. Within 2 minutes of the phone's time, the phone's time stands (never later than the tap); further apart, the server's tap time is recorded and the office is asked to look. A Clock Out or job time stop it proves this way keeps its real time however old; without it, a stop older than 12 hours is recorded at the 12-hour limit and flagged (T6). Send it with every queued tap, clock-outs included."
+                  },
+                  "tapTimeUnverified": {
+                    "type": [
+                      "boolean",
+                      "null"
+                    ],
+                    "description": "True when the phone restarted between the tap and this send, so there is no stopwatch reading (send no tapElapsedMs). A tap more than 2 minutes old keeps the phone's time and is flagged for the office."
+                  },
+                  "deviceClockChanged": {
+                    "type": [
+                      "boolean",
+                      "null"
+                    ],
+                    "description": "True when the phone's clock was changed by hand since the phone last synced. The tap is flagged for the office."
                   },
                   "note": {
                     "type": [
@@ -8182,7 +8564,7 @@
         },
         "responses": {
           "200": {
-            "description": "Day ended.",
+            "description": "Day ended, or the automatic close of the day this tap belongs to replaced (replacedAutoClose).",
             "content": {
               "application/json": {
                 "schema": {
@@ -8201,13 +8583,12 @@
                         }
                       ]
                     },
-                    "closedEntries": {
-                      "type": "integer"
+                    "replacedAutoClose": {
+                      "type": "boolean"
                     }
                   },
                   "required": [
-                    "day",
-                    "closedEntries"
+                    "day"
                   ]
                 }
               }
@@ -8224,7 +8605,7 @@
             }
           },
           "403": {
-            "description": "Time tracking access denied, or no organization on the session.",
+            "description": "Time tracking access denied, no organization on the session, or code PAYROLL_OFF: the company has the time tracking add-on off (GET /api/time-tracking/day says payrollAddon: false). Don't retry; hide Clock In/Out and the other payroll controls.",
             "content": {
               "application/json": {
                 "schema": {
@@ -8234,7 +8615,7 @@
             }
           },
           "404": {
-            "description": "No day is running (code NO_OPEN_DAY).",
+            "description": "No day is running (code NO_OPEN_DAY). Also when the tap was only flagged for the office.",
             "content": {
               "application/json": {
                 "schema": {
@@ -8244,7 +8625,7 @@
             }
           },
           "409": {
-            "description": "The day was already closed.",
+            "description": "The day was already closed; or code DAY_CLOSED_AUTOMATICALLY: the tap belongs to an earlier day the safety net closed, and was flagged for the office.",
             "content": {
               "application/json": {
                 "schema": {
@@ -8512,7 +8893,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Fences, office first when requested.",
+            "description": "Fences, office first when requested. No job fences for someone the office turned job-site tracking off for (clock-config jobSiteTracking false), except with includeClosed for the manual picker.",
             "content": {
               "application/json": {
                 "schema": {
@@ -8559,7 +8940,7 @@
     },
     "/api/time-tracking/active": {
       "get": {
-        "summary": "My open entries right now (or the team's).",
+        "summary": "My open entries right now, or who is on the clock.",
         "tags": [
           "time-tracking"
         ],
@@ -8591,22 +8972,33 @@
             "schema": {
               "type": "string",
               "enum": [
-                "team"
+                "team",
+                "me"
               ]
             },
-            "description": "Everyone on the clock. Requires time_tracking.view_all."
+            "description": "`team`: everyone on the clock, one OnTheClockRow per person; requires time_tracking.view_all. `me`: the caller's own row while on the clock. Without scope: the caller's open entries."
           }
         ],
         "responses": {
           "200": {
-            "description": "Open entries. Normally zero or one for a single user.",
+            "description": "Without scope: open entries, normally zero or one. With scope: one OnTheClockRow per person on the clock.",
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "array",
-                  "items": {
-                    "$ref": "#/components/schemas/TimeEntry"
-                  }
+                  "anyOf": [
+                    {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/TimeEntry"
+                      }
+                    },
+                    {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/OnTheClockRow"
+                      }
+                    }
+                  ]
                 }
               }
             }
@@ -8772,8 +9164,8 @@
     },
     "/api/time-tracking/clock-in": {
       "post": {
-        "summary": "Clock in to a job or the office by hand.",
-        "description": "A deliberate button press. On the day model a press with no day running starts the day at that moment; a fence-driven clock-in from an old-model client cannot, and is refused.",
+        "summary": "Start time on a job or at the office by hand.",
+        "description": "A deliberate button press. The entry joins the person's work day when one is running. With none running: a job timer press (startDay: false) records job time only and never starts the paid day; a Clock In press (startDay omitted: older iPhones' job picker, the office's \"Clock X in\") starts the day at that moment; an automatic clock-in is refused with NO_OPEN_DAY, because the fence crossing already records the arrival. A person starting their own job time away from the job's site, or with no usable location, is asked first (send canConfirmAway: 409 JOB_TIME_AWAY carries the question; resend with confirmAway once they say yes) and the entry is flagged (startCheck) for the office to approve, move or not count. Older apps start straight away, flagged the same.",
         "tags": [
           "time-tracking"
         ],
@@ -8833,6 +9225,11 @@
                     "type": "string",
                     "description": "Clock someone else in. Requires time_tracking.edit_all."
                   },
+                  "note": {
+                    "type": "string",
+                    "maxLength": 2000,
+                    "description": "Why, when clocking someone else in. Required with userId."
+                  },
                   "lat": {
                     "type": "number"
                   },
@@ -8846,6 +9243,10 @@
                       "auto"
                     ]
                   },
+                  "startDay": {
+                    "type": "boolean",
+                    "description": "false: a job timer press, job time only; it never starts the paid day. Omitted: a Clock In press starts the day when none is running."
+                  },
                   "notes": {
                     "type": "string"
                   },
@@ -8858,7 +9259,7 @@
                   "occurredAt": {
                     "type": "string",
                     "format": "date-time",
-                    "description": "When the tech actually arrived. The server clamps it."
+                    "description": "When the tech actually arrived, by the phone's clock. The server checks it against its own (tapElapsedMs) and clamps it. From the web (device 'web') it is ignored: the server's receipt time is used."
                   },
                   "accuracyM": {
                     "type": [
@@ -8877,6 +9278,36 @@
                       "web",
                       "android"
                     ]
+                  },
+                  "canConfirmAway": {
+                    "type": "boolean",
+                    "description": "This app can ask the person before starting job time away from the job (it handles 409 JOB_TIME_AWAY)."
+                  },
+                  "confirmAway": {
+                    "type": "boolean",
+                    "description": "The person said yes to starting away from the job."
+                  },
+                  "tapElapsedMs": {
+                    "type": [
+                      "integer",
+                      "null"
+                    ],
+                    "minimum": 0,
+                    "description": "Milliseconds from the tap to this send, from the phone's monotonic clock (a stopwatch the person can't change). An offline replay sends the time since the tap. The server's tap time is its own clock when the request arrives minus this. Within 2 minutes of the phone's time, the phone's time stands (never later than the tap); further apart, the server's tap time is recorded and the office is asked to look. A Clock Out or job time stop it proves this way keeps its real time however old; without it, a stop older than 12 hours is recorded at the 12-hour limit and flagged (T6). Send it with every queued tap, clock-outs included."
+                  },
+                  "tapTimeUnverified": {
+                    "type": [
+                      "boolean",
+                      "null"
+                    ],
+                    "description": "True when the phone restarted between the tap and this send, so there is no stopwatch reading (send no tapElapsedMs). A tap more than 2 minutes old keeps the phone's time and is flagged for the office."
+                  },
+                  "deviceClockChanged": {
+                    "type": [
+                      "boolean",
+                      "null"
+                    ],
+                    "description": "True when the phone's clock was changed by hand since the phone last synced. The tap is flagged for the office."
                   }
                 }
               }
@@ -8895,7 +9326,7 @@
             }
           },
           "400": {
-            "description": "Validation failure, or jobId missing on a job clock-in.",
+            "description": "Validation failure, jobId missing on a job clock-in, or no note when clocking someone else in.",
             "content": {
               "application/json": {
                 "schema": {
@@ -8915,7 +9346,7 @@
             }
           },
           "403": {
-            "description": "Time tracking access denied, or no organization on the session.",
+            "description": "Time tracking access denied, or no organization on the session. PAYROLL_OFF: a Clock In press that would start the day at a company with the time tracking add-on off. JOB_TIME_OFF: the company has both the time tracking add-on and location tracking off, so job time isn't used; stopping running job time still works.",
             "content": {
               "application/json": {
                 "schema": {
@@ -8935,7 +9366,7 @@
             }
           },
           "409": {
-            "description": "Already clocked in at this site (code ALREADY_CLOCKED_IN_SAME_JOB). The body carries the existing entry — adopt it.",
+            "description": "ALREADY_CLOCKED_IN_SAME_JOB: already at this site; the body carries the existing entry — adopt it. ALREADY_CLOCKED_IN_OTHER_JOB: an automatic clock-in while another entry is open; the body carries it. NO_OPEN_DAY: an automatic clock-in with no work day running; the fence crossing records the arrival. JOB_SITE_TRACKING_OFF: an automatic clock-in for someone the office turned job-site tracking off for; start job time by hand. PERIOD_LOCKED: an admin clock-in inside a locked pay period. JOB_TIME_AWAY: starting job time away from the job (reason 'away', with distanceM) or with no usable location (reason 'no_location'); show message as the question and resend with confirmAway: true.",
             "content": {
               "application/json": {
                 "schema": {
@@ -8949,12 +9380,30 @@
                     },
                     "entry": {
                       "$ref": "#/components/schemas/TimeEntry"
+                    },
+                    "reason": {
+                      "type": "string",
+                      "enum": [
+                        "away",
+                        "no_location"
+                      ]
+                    },
+                    "distanceM": {
+                      "type": [
+                        "integer",
+                        "null"
+                      ]
+                    },
+                    "jobName": {
+                      "type": [
+                        "string",
+                        "null"
+                      ]
                     }
                   },
                   "required": [
                     "message",
-                    "code",
-                    "entry"
+                    "code"
                   ]
                 }
               }
@@ -9053,7 +9502,7 @@
                   "occurredAt": {
                     "type": "string",
                     "format": "date-time",
-                    "description": "When the tech actually left. Clamped to [entry.clockIn, now]."
+                    "description": "When the tech actually left, by the phone's clock. Checked against the server's (tapElapsedMs) and clamped to [entry.clockIn, now], and to the last 12 hours unless tapElapsedMs proves it (T6). From the web (device 'web') it is ignored: the server's receipt time is used."
                   },
                   "accuracyM": {
                     "type": [
@@ -9072,6 +9521,28 @@
                       "web",
                       "android"
                     ]
+                  },
+                  "tapElapsedMs": {
+                    "type": [
+                      "integer",
+                      "null"
+                    ],
+                    "minimum": 0,
+                    "description": "Milliseconds from the tap to this send, from the phone's monotonic clock (a stopwatch the person can't change). An offline replay sends the time since the tap. The server's tap time is its own clock when the request arrives minus this. Within 2 minutes of the phone's time, the phone's time stands (never later than the tap); further apart, the server's tap time is recorded and the office is asked to look. A Clock Out or job time stop it proves this way keeps its real time however old; without it, a stop older than 12 hours is recorded at the 12-hour limit and flagged (T6). Send it with every queued tap, clock-outs included."
+                  },
+                  "tapTimeUnverified": {
+                    "type": [
+                      "boolean",
+                      "null"
+                    ],
+                    "description": "True when the phone restarted between the tap and this send, so there is no stopwatch reading (send no tapElapsedMs). A tap more than 2 minutes old keeps the phone's time and is flagged for the office."
+                  },
+                  "deviceClockChanged": {
+                    "type": [
+                      "boolean",
+                      "null"
+                    ],
+                    "description": "True when the phone's clock was changed by hand since the phone last synced. The tap is flagged for the office."
                   }
                 }
               }
@@ -9080,7 +9551,7 @@
         },
         "responses": {
           "200": {
-            "description": "Entry closed.",
+            "description": "Entry closed; or, for a stop tapElapsedMs proves that is earlier than the automatic close of the job time there, that close replaced (T6).",
             "content": {
               "application/json": {
                 "schema": {
@@ -9120,7 +9591,7 @@
             }
           },
           "404": {
-            "description": "No open entry at that site.",
+            "description": "No open entry at that site. Also when the stop belongs to job time the safety net closed and was only flagged for the office.",
             "content": {
               "application/json": {
                 "schema": {
@@ -9145,7 +9616,7 @@
     "/api/time-tracking/switch": {
       "post": {
         "summary": "Move my clock to another job in one atomic call.",
-        "description": "Closes the caller's open entry and opens one on the target. One request instead of clock-out + clock-in, so an offline drop between the two cannot strand the tech clocked out. Own entry only.",
+        "description": "Closes the caller's open entry and opens one on the target. One request instead of clock-out + clock-in, so an offline drop between the two cannot strand the tech clocked out. Own entry only. Moving job time to a job the person isn't at, or with no usable location, is asked first (send canConfirmAway: 409 JOB_TIME_AWAY carries the question; resend with confirmAway once they say yes) and the new entry is flagged (startCheck) for the office. Older apps move straight away, flagged the same. switchAt is a time the person picked, so earlier than the tap is normal. With tapElapsedMs it is never later than the tap by the server's clock, and more than 2 minutes later is replaced by the tap time and flagged (opened.clockInCheck). tapTimeUnverified doesn't apply; deviceClockChanged flags it.",
         "tags": [
           "time-tracking"
         ],
@@ -9180,6 +9651,43 @@
                   },
                   "lng": {
                     "type": "number"
+                  },
+                  "accuracyM": {
+                    "type": [
+                      "number",
+                      "null"
+                    ],
+                    "minimum": 0
+                  },
+                  "canConfirmAway": {
+                    "type": "boolean",
+                    "description": "This app can ask the person before moving job time to a job they aren't at (it handles 409 JOB_TIME_AWAY)."
+                  },
+                  "confirmAway": {
+                    "type": "boolean",
+                    "description": "The person said yes to moving it anyway."
+                  },
+                  "tapElapsedMs": {
+                    "type": [
+                      "integer",
+                      "null"
+                    ],
+                    "minimum": 0,
+                    "description": "Milliseconds from the tap to this send, from the phone's monotonic clock (a stopwatch the person can't change). An offline replay sends the time since the tap. The server's tap time is its own clock when the request arrives minus this. Within 2 minutes of the phone's time, the phone's time stands (never later than the tap); further apart, the server's tap time is recorded and the office is asked to look. A Clock Out or job time stop it proves this way keeps its real time however old; without it, a stop older than 12 hours is recorded at the 12-hour limit and flagged (T6). Send it with every queued tap, clock-outs included."
+                  },
+                  "tapTimeUnverified": {
+                    "type": [
+                      "boolean",
+                      "null"
+                    ],
+                    "description": "True when the phone restarted between the tap and this send, so there is no stopwatch reading (send no tapElapsedMs). A tap more than 2 minutes old keeps the phone's time and is flagged for the office."
+                  },
+                  "deviceClockChanged": {
+                    "type": [
+                      "boolean",
+                      "null"
+                    ],
+                    "description": "True when the phone's clock was changed by hand since the phone last synced. The tap is flagged for the office."
                   }
                 },
                 "required": [
@@ -9237,7 +9745,7 @@
             }
           },
           "403": {
-            "description": "Time tracking access denied, or no organization on the session.",
+            "description": "Time tracking access denied, or no organization on the session. JOB_TIME_OFF: the company has both the time tracking add-on and location tracking off, so job time isn't used; stopping running job time still works.",
             "content": {
               "application/json": {
                 "schema": {
@@ -9256,6 +9764,47 @@
               }
             }
           },
+          "409": {
+            "description": "PERIOD_LOCKED: the switch time is inside a locked pay period. JOB_TIME_AWAY: the person isn't at the target job (reason 'away', with distanceM) or has no usable location (reason 'no_location'); nothing moved. Show message as the question and resend with confirmAway: true.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "message": {
+                      "type": "string"
+                    },
+                    "code": {
+                      "type": "string"
+                    },
+                    "reason": {
+                      "type": "string",
+                      "enum": [
+                        "away",
+                        "no_location"
+                      ]
+                    },
+                    "distanceM": {
+                      "type": [
+                        "integer",
+                        "null"
+                      ]
+                    },
+                    "jobName": {
+                      "type": [
+                        "string",
+                        "null"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "message",
+                    "code"
+                  ]
+                }
+              }
+            }
+          },
           "426": {
             "description": "Client major below minClientVersion.",
             "content": {
@@ -9683,7 +10232,7 @@
             }
           },
           "403": {
-            "description": "Time tracking access denied, or no organization on the session.",
+            "description": "Time tracking access denied, no organization on the session, or code PAYROLL_OFF: the company has the time tracking add-on off (GET /api/time-tracking/day says payrollAddon: false). Don't retry; hide Clock In/Out and the other payroll controls.",
             "content": {
               "application/json": {
                 "schema": {
@@ -9968,6 +10517,16 @@
               }
             }
           },
+          "403": {
+            "description": "Time tracking access denied, no organization on the session, or code PAYROLL_OFF: the company has the time tracking add-on off (GET /api/time-tracking/day says payrollAddon: false). Don't retry; hide Clock In/Out and the other payroll controls.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
           "409": {
             "description": "A request for those dates is already waiting.",
             "content": {
@@ -9990,6 +10549,197 @@
           }
         }
       }
+    },
+    "/api/account/deletion-request": {
+      "post": {
+        "summary": "Ask for my account to be deleted.",
+        "description": "Nothing is deleted by this call. The request goes to the company's owner and Team admins (bell, push and email) and to ServiceAi support (email); the company removes the account. Asking again while a request is pending answers that request with 200 and creates nothing; everyone is reminded at most once a day. The reason is never put in a push.",
+        "tags": [
+          "account"
+        ],
+        "parameters": [
+          {
+            "name": "X-Client-Version",
+            "in": "header",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "example": "1.0.0"
+            },
+            "description": "Semver of the calling app build. Drives the 426 / soft-upgrade handshake."
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "reason": {
+                    "type": [
+                      "string",
+                      "null"
+                    ],
+                    "maxLength": 1000,
+                    "description": "Optional. Trimmed; at most 1000 characters after trimming."
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "A request was already pending: this is that request.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AccountDeletionRequest"
+                }
+              }
+            }
+          },
+          "202": {
+            "description": "Request created.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AccountDeletionRequest"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation failure (a reason longer than 1000 characters).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Not signed in.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "No organization on the session, or viewing the app as someone else.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "426": {
+            "description": "Client major below minClientVersion.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UpgradeRequiredEnvelope"
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "Too many requests from this person; try again later.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      },
+      "get": {
+        "summary": "My newest account deletion request.",
+        "tags": [
+          "account"
+        ],
+        "parameters": [
+          {
+            "name": "X-Client-Version",
+            "in": "header",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "example": "1.0.0"
+            },
+            "description": "Semver of the calling app build. Drives the 426 / soft-upgrade handshake."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The newest request, whatever its status.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AccountDeletionRequest"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Not signed in.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "No organization on the session.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "No request yet.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "message": {
+                      "type": "string",
+                      "example": "No deletion request"
+                    }
+                  },
+                  "required": [
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "426": {
+            "description": "Client major below minClientVersion.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UpgradeRequiredEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
     }
   },
   "webhooks": {}