Update mapped clock-in data · Fieldmotion API

When to use this endpoint

Use UserClockin_updateData for CRM2’s Clock-ins editor. Prefer scalar IDs whenever changing the user, date, start, or end of a session.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session.

The handler checks neither Clock-ins edit permission nor ownership of the row/user. Any authenticated caller that can reach the route can edit tenant rows.

Parameters

Parameter	Type	Required	Description
`id`	Integer string or native array	Yes	Target ID or IDs. JSON array text is not decoded. Bulk mode discards per-row errors/warnings and its prevalidation is unsafe for session fields.
`userID / user / date`	Integer / YYYY-MM-DD	No	Both user keys map to `user_id`. Only `userID` participates in the wrapper’s session prevalidation; the `user` alias bypasses it and should not be used for writes. Dates use the shared strict validator.
`clockIn / clockOut`	Unix seconds	No	Replacement epochs. Changing either recalculates gross `duration`. A supplied `clockOut` at or below zero invokes the special normalized-clear path.
`clockInCDate / clockOutCDate / clockInDiff / clockOutDiff / duration`	Integer	No	Mapped creation, offset, and duration fields. The handler can override end metadata/duration when `clockOut` or either session time is supplied.
`clockInNotes / clockOutNotes / flagNotes / notes`	String	No	Complete mapped text replacements. `notes` maps to the JSON database column as text.
`flagged / userSignedOff / sourceType`	Integer	No	Mapped status/source values; there is no enum/range validation in the field map.
`clockInGeo / clockOutGeo / meta / breaks`	JSON value or JSON text	No	Complete JSON replacements. Native values are encoded by the shared mapper; nonblank text is not schema-validated.
`clockInGeoDist / clockOutGeoDist`	Integer	No	Mapped distance values.
`noRecord`	Native array	No	Internal list of mapped keys whose generic audit entries should be marked hidden.

Example request

$result = FM_api('UserClockin_updateData', [
	'id' => '481',
	'date' => '2026-09-26',
	'clockIn' => '1790413200',
	'clockOut' => '1790442000',
	'breaks' => json_encode(['total' => 1800, 'breaks' => []]),
]);

Example response

{
  "ok": 1
}

A no-op scalar update returns {"warning":"No Change."}; a missing row returns {"warning":"No data."}; supplying only unknown fields returns {"warning":"no updated fields."}. Supplying only id returns {"ok":1}.

Errors and unusual responses

Response	Condition
`{"error":"not logged in"}`	No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs.
`{"error":"missing or invalid parameter: id"}`	The `id` key is absent. Scalar zero is handled later as `No data.`.
`{"error":"Clock-out time must be after clock-in time."}`	A scalar session edit would leave a positive end not later than its positive start.
`{"error":"This clocking period overlaps an existing entry for this user."}`	A scalar session edit would overlap another row for the resulting user.
`{"error":"invalid date parameter: date"}`	The mapped date is not a strict SQL `YYYY-MM-DD` value.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

For a scalar existing row, validation combines supplied session values with stored values. Moving a row to another userID validates against that user’s sessions.
The mapped user alias is not in the wrapper’s session-field list. Supplying it can move a row without overlap validation; use userID instead.
Supplying clockOut<=0 first clears clockout/clockout_cdate to SQL null, resets end difference/duration to zero, and removes those keys before the generic update. This direct clear is not included in generic audit history.
When setting a positive end for the first time, the server records current clockOutCDate and current-minus-end clockOutDiff. Later end corrections preserve existing creation metadata.
Changing either session epoch recalculates gross duration without subtracting breaks. Unknown request keys are ignored.

Side effects

Updates mapped fields, invalidates the user-clock-ins cache, and writes generic per-field history for changes made by the shared updater.
The clock-in table has no mapped last-edited field, so this route does not advance a row timestamp. The special clear and generic update are separate, nontransactional writes.

See it in Fieldmotion

CRM1

CRM1 uses focused setters rather than this mapped route.

CRM2

The main Users → Clock-ins table uses this route for flags, notes, breaks, dates, and start/end corrections.

Related endpoints

UserClockin_updateField applies one raw mapped value and skips session invariants.
UserClockins_getDataTable reads the same field map.