Fieldmotion API Getting started

User clock-ins

Set a clock-out time

POST /a/UserClockin_setClockoutTime

Replace one session’s clock-out epoch, blocking earlier open sessions and overlapping or reversed intervals.

When to use this endpoint

Use UserClockin_setClockoutTime for quick clock-out and the CRM1 time editor. Handle earlier_clockins_open through the repair endpoint before retrying.

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 row ownership nor page permissions. Quick-clock callers first find the signed-in user’s row, but the server accepts any tenant row ID.

Parameters

ParameterTypeRequiredDescription
idInteger stringYesExisting tenant clock-in ID; must integer-convert above zero.
timeUnix secondsNoReplacement end epoch. Omission, blank, and nonnumeric text become 0.

Example request

$result = FM_api('UserClockin_setClockoutTime', [
	'id' => '481',
	'time' => (string) time(),
]);

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."}A positive proposed end is not later than the stored positive start.
{"error":"...","error_code":"earlier_clockins_open","earlier_sessions":[...]}A positive clock-out is requested while that user has an earlier open session.
{"error":"This clocking period overlaps an existing entry for this user."}The resulting interval overlaps another stored session.

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

Behaviour and edge cases

  • Earlier-session blocking runs only for a positive proposed time. It returns IDs, dates, and starts for every earlier open row.
  • Gross duration becomes proposed end minus stored start when both are positive; otherwise zero. Breaks are not subtracted from the stored duration.
  • On the first changed end value, missing creation metadata is generated from server time. Later corrections preserve the original clockout_cdate and clockout_diff.
  • An unchanged epoch is a successful no-op, and write failures are not surfaced.

Side effects

  • Updates clockout and duration, may initialize clockout_cdate/clockout_diff, and invalidates the user-clock-ins cache.
  • Does not change the calendar date, write audit history, or close earlier sessions itself.

See it in Fieldmotion

CRM1

The header Clock out widget and the Clock-ins row detail use this route. The widget can invoke automatic earlier-session repair.

CRM2

The quick clock menu uses this route and the same repair-and-retry flow. The main editor uses UserClockin_updateData.

Related endpoints