Units, jobs & plan

All three need cleaning:read:jobs.

`GET /units`

Every apartment the crew is the default cleaner for — what a cleaner needs at the door and nothing more. Units the crew merely covers a job on (a hand-over from the office) arrive together with that job in GET /jobs, flagged covering: true.

{
  "units": [
    {
      "id": "0190c…",
      "name": "Marina Loft · 2BR",
      "area": "Dubai Marina",
      "building": "Marina Heights",
      "address": "Marina Heights, Tower B, 23rd floor",
      "lat": 25.0805,
      "lng": 55.1403,
      "bedrooms": 2,
      "bathrooms": 2,
      "sizeSqm": 118,
      "checkinTime": "15:00",
      "checkoutTime": "11:00",
      "covering": false
    }
  ]
}

`GET /jobs`

Every job the crew is on duty for whose window touches [from, to), with progress merged in, plus the units involved and anonymous occupancy spans — the reason behind the gaps in the calendar, never the who.

Query parameter	Required	Meaning
`from` / `to`	no	`[from, to)`; default five weeks starting a week ago; at most 92 days

{
  "from": "2026-09-01",
  "to": "2026-10-06",
  "units": [ { "id": "0190c…", "name": "Marina Loft · 2BR", "…": "…", "covering": false } ],
  "jobs": [
    {
      "key": "turnover:0191a…",
      "kind": "turnover",
      "unitId": "0190c…",
      "date": "2026-09-04",
      "endDate": "2026-09-05",
      "notBefore": "12:00",
      "lateCheckout": true,
      "dueTime": "13:00",
      "nextArrival": { "date": "2026-09-05", "time": "13:00", "early": true },
      "flexible": false,
      "blockDays": 0,
      "blockRule": null,
      "pax": 3,
      "week": null,
      "status": "open",
      "startedAt": null,
      "finishedAt": null,
      "minutes": null,
      "notes": null,
      "covered": false
    },
    {
      "key": "midstay:0191c…:2026-09-11",
      "kind": "mid_stay",
      "unitId": "0190d…",
      "date": "2026-09-11",
      "endDate": "2026-09-11",
      "notBefore": null,
      "lateCheckout": false,
      "dueTime": null,
      "nextArrival": null,
      "flexible": false,
      "blockDays": 0,
      "blockRule": null,
      "pax": 2,
      "week": 1,
      "status": "open",
      "…": "…"
    }
  ],
  "stays": [
    { "id": "0191a…", "unitId": "0190c…", "arrival": "2026-09-01", "departure": "2026-09-04", "kind": "stay", "pax": 3, "earlyCheckin": null, "lateCheckout": "12:00" }
  ]
}

Field	Notes
`date` / `endDate`	The window: first day work is possible (the departure), last day it may be done (the next arrival or the block due date)
`notBefore`	Apartment free from this time on the first day — late checkout included
`dueTime`	Must be guest-ready by this time on the last day — early check-in included; `null` when no arrival waits in the window
`nextArrival.early`	The next guest arrives before the standard check-in time
`flexible`	Nobody is waiting; any day of the window works
`blockDays` / `blockRule`	The turnover block the agency keeps after this checkout, and the rule that raised it (e.g. “crew short-staffed 10–20 Aug”)
`pax`	Head count of the stay that caused the job — for sizing, not identity
`week`	Mid-stay only: week 1, 2, … of the running stay
`status`	`open`, `in_progress`, `done`, `waived` (the guest declined this week’s cleaning — nothing to do)
`covered`	Handed to your crew by the office; the unit normally belongs to another partner
`stays[].kind`	`stay` or `blocked` (maintenance / owner block) — occupancy, anonymous

`GET /plan`

The day’s stops in suggested driving order with time slots — the same list a cleaner opens in the car. The router is the agency’s own (the printed office plan uses it too), so partner and office never argue about the order.

Query parameter	Meaning
`date`	ISO date; default today

{
  "date": "2026-09-04",
  "stops": [
    {
      "key": "turnover:0191a…",
      "kind": "turnover",
      "unitId": "0190c…",
      "unitName": "Marina Loft · 2BR",
      "building": "Marina Heights",
      "area": "Dubai Marina",
      "address": "Marina Heights, Tower B, 23rd floor",
      "lat": 25.0805, "lng": 55.1403,
      "bedrooms": 2, "bathrooms": 2,
      "date": "2026-09-04", "endDate": "2026-09-05",
      "notBefore": "12:00", "dueTime": null,
      "status": "open",
      "order": 1,
      "eta": "12:00",
      "slot": "12:00–14:00",
      "atRisk": false,
      "overdue": false,
      "…": "…"
    }
  ],
  "routeKm": 18.4
}

Field	Notes
`order` / `eta` / `slot`	Driving order, arrival time and working slot; `null` when the unit has no coordinates
`atRisk`	The deadline cannot be met in this order — this day needs a second team
`overdue`	A turnover whose window has passed without a finish report; it keeps appearing for 14 days
`routeKm`	Straight-line length of the suggested tour

Done jobs of the day stay in the list (without an order) so the plan reads as a checklist; waived cleanings are left out.