Clock in

Crew module

POST/time-entries/clock-intimeEntries.clockIn

Opens a time entry inside the shift geofence. Protects against double clock-in across devices; an overlapping entry is refused. Compass replays queued punches with the same Idempotency-Key. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.

Requires the capability crew.time_entry.write.
OAuth scopes: crew.
Send an Idempotency-Key header. A replay with the same key returns the original response.
Error statuses: 400, 401, 409, 422, 429. Errors are RFC 9457 problem details.

Request body: TimeEntryClockInRequest

timeEntries.clockIn: TimeEntryClockInRequest
Field	Type	Required	Description
project_id	string (uuid)	Yes	Identifier of the project the caller clocks in on.
shift_id	string (uuid) \| null	No	Identifier of the Accepted shift of the caller.
engagement_id	string (uuid) \| null	No	Identifier of the caller's open engagement, when they work as external crew.
punch_id	string (uuid)	No	Client punch id; a replay with the same id returns the same entry.
device_time	string (date-time)	No	When the punch was made on the device; defaults to now.
monotonic_offset_ms	integer (int64)	No	Milliseconds since the punch on the device's monotonic clock, for a punch queued offline.Constraints: range 0 to any
latitude	number \| null	No	WGS 84 latitude.Constraints: range -90 to 90
longitude	number \| null	No	WGS 84 longitude.Constraints: range -180 to 180
accuracy_m	number \| null	No	Location accuracy in metres.Constraints: range 0 to any
geofence_id	string (uuid) \| null	No	Identifier of the geofence the location is checked against.

{
  "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "shift_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "punch_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "device_time": "2026-10-08T14:30:00Z",
  "monotonic_offset_ms": 0,
  "latitude": 25.7617,
  "longitude": -80.1918,
  "accuracy_m": 12,
  "geofence_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"
}

Response 201: TimeEntry

timeEntries.clockIn: TimeEntry
Field	Type	Required	Description
id	string (uuid)	Yes	Identifier of the time entry.
org_id	string (uuid)	Yes	Identifier of the owning organization, derived from the parent row and never accepted from the caller.
created_at	string (date-time)	Yes	When the row was created.
created_by	string (uuid) \| null	Yes	Identifier of the person who created the row; null when a seed, platform or system process created it.
updated_at	string (date-time)	Yes	When the row was last updated.
updated_by	string (uuid) \| null	Yes	Identifier of the person who last updated the row; null when a seed, platform or system process updated it.
shift_id	string (uuid) \| null	Yes	Identifier of the shift.
clock_in	string (date-time)	Yes	Clock in.
clock_out	string (date-time) \| null	Yes	Clock out.
break_minutes	integer	Yes	Break minutes.Constraints: range 0 to any
kiosk_device_id	string (uuid) \| null	Yes	Identifier of the kiosk device.
project_id	string (uuid)	Yes	Identifier of the project worked.
membership_id	string (uuid) \| null	Yes	Identifier of the membership of the person who worked; null for external crew, who carry an engagement.
engagement_id	string (uuid) \| null	Yes	Identifier of the engagement of the person who worked when external crew; null for members.
source	"Web" \| "Mobile" \| "Kiosk"	Yes	Where the punch came from.
auto_closed_at	string (date-time) \| null	Yes	When a forgotten clock-out was closed automatically at 16 hours.
needs_review	boolean	Yes	Whether the entry was closed automatically and awaits review.
meal_out_at	string (date-time) \| null	Yes	Effective time of the entry's first Break Start punch (meal out).
meal_in_at	string (date-time) \| null	Yes	Effective time of the entry's last Break End punch (meal in).

{
  "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "created_at": "2026-10-08T14:30:00Z",
  "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "updated_at": "2026-10-08T14:30:00Z",
  "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "shift_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "clock_in": "2026-10-08T14:30:00Z",
  "clock_out": "2026-10-08T14:30:00Z",
  "break_minutes": 30,
  "kiosk_device_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "source": "Web",
  "auto_closed_at": "2026-10-08T14:30:00Z",
  "needs_review": false,
  "meal_out_at": "2026-10-08T14:30:00Z",
  "meal_in_at": "2026-10-08T14:30:00Z"
}

Code samples

curl -X POST "$XOS_BASE_URL/time-entries/clock-in" \
  -H "Authorization: Bearer $XOS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","shift_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","engagement_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","punch_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","device_time":"2026-10-08T14:30:00Z","monotonic_offset_ms":0,"latitude":25.7617,"longitude":-80.1918,"accuracy_m":12,"geofence_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"}'

const { data } = await xos.timeEntries.clockIn({
    "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
    "shift_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
    "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
    "punch_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
    "device_time": "2026-10-08T14:30:00Z",
    "monotonic_offset_ms": 0,
    "latitude": 25.7617,
    "longitude": -80.1918,
    "accuracy_m": 12,
    "geofence_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"
  });

response = xos.time_entries.clock_in({"project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shift_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "punch_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "device_time": "2026-10-08T14:30:00Z", "monotonic_offset_ms": 0, "latitude": 25.7617, "longitude": -80.1918, "accuracy_m": 12, "geofence_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"})

xos time-entries clock-in --data '{"project_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","shift_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","engagement_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","punch_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","device_time":"2026-10-08T14:30:00Z","monotonic_offset_ms":0,"latitude":25.7617,"longitude":-80.1918,"accuracy_m":12,"geofence_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"}'