@serviceai/api-spec 1.2.418 → 1.2.419

package/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: ServiceAi API
-  version: 1.2.418
+  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
@@ -41,6 +41,8 @@ tags:
     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:
   schemas:
     ErrorEnvelope:
@@ -87,7 +89,7 @@ components:
       properties:
         apiVersion:
           type: string
-          example: 1.2.418
+          example: 1.2.419
         minClientVersion:
           type: string
           example: 1.0.0
@@ -2091,6 +2093,71 @@ components:
           minLength: 1
       required:
         - 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:
@@ -2189,6 +2256,46 @@ components:
         breakMinutes:
           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
@@ -2199,7 +2306,7 @@ components:
           description: Enrichment on /active and /entries. 'Office' for an office entry.
         userName:
           type: string
-          description: Enrichment on /entries and /active?scope=team.
+          description: Enrichment on /entries.
       required:
         - id
         - organizationId
@@ -2356,6 +2463,22 @@ components:
           type:
             - string
             - '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
@@ -2451,6 +2574,28 @@ components:
     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.
@@ -2507,6 +2652,8 @@ components:
             - address
           description: The office fence, when the org profile address is on the map.
       required:
+        - payrollAddon
+        - payroll
         - dayModel
         - open
         - today
@@ -2648,11 +2795,40 @@ components:
         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:
         - clientEventId
         - 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
       properties:
@@ -2802,6 +2978,12 @@ components:
         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:
         - serverResolver
         - dwellSeconds
@@ -2987,6 +3169,11 @@ components:
           type: string
           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:
@@ -3069,12 +3256,73 @@ components:
         - from
         - to
         - today
+        - payrollAddon
         - hours
         - attendance
         - shifts
         - timeOff
         - 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: {}
 paths:
   /api/version:
@@ -4272,13 +4520,33 @@ paths:
                               placementSource:
                                 type: string
                                 enum: *ref_1
+                              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:
                               - position
                               - width
                               - height
                           description: >-
                             RoomPlan-classified doors. Distinct from `windows[]` and `openings[]`; append-room
-                            `entryDoorwayId` tokens of the form `…-door-<idx>` resolve into THIS array only.
+                            `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
                           items:
@@ -4513,13 +4781,34 @@ paths:
                                   placementSource:
                                     type: string
                                     enum: *ref_1
+                                  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:
                                   - position
                                   - width
                                   - height
                               description: >-
                                 RoomPlan-classified doors. Distinct from `windows[]` and `openings[]`; append-room
-                                `entryDoorwayId` tokens of the form `…-door-<idx>` resolve into THIS array only.
+                                `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
                               items:
@@ -5203,7 +5492,37 @@ paths:
                     - string
                     - '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:
                     - string
@@ -5229,7 +5548,10 @@ paths:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
         '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:
@@ -5265,12 +5587,19 @@ paths:
                 $ref: '#/components/schemas/UpgradeRequiredEnvelope'
   /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
       parameters:
         - *ref_3
         - *ref_4
+      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:
@@ -5304,7 +5633,37 @@ paths:
                     - string
                     - '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:
                     - string
@@ -5312,7 +5671,7 @@ paths:
                   maxLength: 2000
       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:
@@ -5324,11 +5683,10 @@ paths:
                       - type:
                           - object
                           - 'null'
-                  closedEntries:
-                    type: integer
+                  replacedAutoClose:
+                    type: boolean
                 required:
                   - day
-                  - closedEntries
         '401':
           description: Not signed in.
           content:
@@ -5336,19 +5694,24 @@ paths:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
         '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:
                 $ref: '#/components/schemas/ErrorEnvelope'
         '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:
                 $ref: '#/components/schemas/ErrorEnvelope'
         '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:
@@ -5507,7 +5870,9 @@ paths:
           description: Prepend the office fence (jobId null). Only send it if this client can decode a null jobId.
       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:
@@ -5534,7 +5899,7 @@ paths:
                 $ref: '#/components/schemas/UpgradeRequiredEnvelope'
   /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
       parameters:
@@ -5547,16 +5912,23 @@ paths:
             type: string
             enum:
               - team
-          description: Everyone on the clock. Requires time_tracking.view_all.
+              - me
+          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'
         '401':
           description: Not signed in.
           content:
@@ -5647,10 +6019,15 @@ paths:
                 $ref: '#/components/schemas/UpgradeRequiredEnvelope'
   /api/time-tracking/clock-in:
     post:
-      summary: Clock in to a job or the office by hand.
+      summary: Start time on a job or at 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.
+        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
       parameters:
@@ -5674,6 +6051,10 @@ paths:
                 userId:
                   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
                 lng:
@@ -5683,6 +6064,11 @@ paths:
                   enum:
                     - manual
                     - 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
                 budgetItemId:
@@ -5692,7 +6078,10 @@ paths:
                 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:
                     - number
@@ -5703,6 +6092,42 @@ paths:
                     - string
                     - 'null'
                   enum: *ref_5
+                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.
       responses:
         '201':
           description: Entry opened.
@@ -5711,7 +6136,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/TimeEntry'
         '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:
@@ -5723,7 +6148,10 @@ paths:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
         '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:
@@ -5736,8 +6164,13 @@ paths:
                 $ref: '#/components/schemas/ErrorEnvelope'
         '409':
           description: >-
-            Already clocked in at this site (code ALREADY_CLOCKED_IN_SAME_JOB). The body carries the existing entry —
-            adopt it.
+            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:
@@ -5749,10 +6182,22 @@ paths:
                     type: string
                   entry:
                     $ref: '#/components/schemas/TimeEntry'
+                  reason:
+                    type: string
+                    enum:
+                      - away
+                      - no_location
+                  distanceM:
+                    type:
+                      - integer
+                      - 'null'
+                  jobName:
+                    type:
+                      - string
+                      - 'null'
                 required:
                   - message
                   - code
-                  - entry
         '426':
           description: Client major below minClientVersion.
           content:
@@ -5798,7 +6243,10 @@ paths:
                 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:
                     - number
@@ -5809,9 +6257,39 @@ paths:
                     - string
                     - 'null'
                   enum: *ref_5
+                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.
       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:
@@ -5835,7 +6313,9 @@ paths:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
         '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:
@@ -5851,7 +6331,13 @@ paths:
       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.
+        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
       parameters:
@@ -5874,6 +6360,47 @@ paths:
                   type: number
                 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:
                 - targetJobId
       responses:
@@ -5907,7 +6434,9 @@ paths:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
         '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:
@@ -5918,6 +6447,36 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
+        '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:
@@ -6174,7 +6733,10 @@ paths:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
         '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:
@@ -6342,6 +6904,15 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
+        '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:
@@ -6354,4 +6925,114 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/UpgradeRequiredEnvelope'
+  /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:
+        - *ref_3
+      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:
+        - *ref_3
+      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: {}