Fieldmotion API Getting started

User clock-ins

Set a clock-in time

POST /a/UserClockin_setClockinTime

Replace one session’s clock-in epoch and recalculate its gross duration after overlap validation.

When to use this endpoint

Use UserClockin_setClockinTime for the legacy CRM1 time editor. CRM2 uses the mapped update route so it can change the calendar date alongside the epoch.

Authentication and permissions

The API call needs an authenticated tenant context, but this legacy handler does not itself call the login guard.

It checks neither page permissions nor ownership of the target row.

Parameters

ParameterTypeRequiredDescription
idInteger stringYesExisting tenant clock-in ID; must integer-convert above zero.
timeUnix secondsNoReplacement epoch after integer conversion. Omission, blank, or nonnumeric text becomes 0, which clears the effective start.

Example request

$result = FM_api('UserClockin_setClockinTime', [
	'id' => '481',
	'time' => '1790413200',
]);

Example response

{
  "ok": 1
}

Errors and unusual responses

ResponseCondition
{"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 integer-converts below 1.
{"error":"clockin does not exist"}No tenant row has that ID.
{"error":"Clock-out time must be after clock-in time."}The stored positive clock-out is not later than the proposed positive start.
{"error":"This clocking period overlaps an existing entry for this user."}The resulting interval overlaps another session for the stored user.

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

Behaviour and edge cases

  • Overlap uses epoch intervals across all dates and permits touching boundaries. Setting time=0 skips interval overlap and is allowed.
  • Gross duration becomes stored clock-out minus the new start when both are positive; otherwise it becomes zero. Break time is not subtracted from this stored value.
  • An unchanged epoch is a successful no-op. Database write failure is not surfaced.

Side effects

  • Updates clockin and duration and invalidates the user-clock-ins cache.
  • Does not change date, clockin_cdate, clockin_diff, notes, or generic audit history.

See it in Fieldmotion

CRM1

Open a Clock-ins row’s Clock-in detail and edit its time.

CRM2

No direct CRM2 caller was found; CRM2 submits epoch/date corrections through UserClockin_updateData.

Related endpoints