Fieldmotion API Getting started

User clock-ins

Create a clock-in session

POST /a/UserClockin_new

Create a CRM-sourced clock-in session after enforcing time ordering and non-overlap for the chosen user.

When to use this endpoint

Use UserClockin_new to add a manual session or start the signed-in user’s quick clock-in. The mobile app uploads through its sync service rather than this route.

Authentication and permissions

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

The handler checks neither add permission nor whether user_id is the signed-in user. An authenticated caller can create a row for any user in the tenant.

Parameters

ParameterTypeRequiredDescription
user_idInteger stringYesTarget tenant user ID; must integer-convert above zero. User existence is not checked before insert.
dateYYYY-MM-DD-looking stringYesCalendar grouping date. Validation checks only four digits, two digits, and two digits; it does not prove the date exists or matches either epoch.
clockinUnix secondsOne of clockin or clockoutStart epoch after integer conversion.
clockoutUnix secondsOne of clockin or clockoutEnd epoch after integer conversion. A positive end paired with a positive start must be later than the start.

Example request

$created = FM_api('UserClockin_new', [
	'user_id' => '18',
	'date' => '2026-09-26',
	'clockin' => '1790413200',
	'clockout' => '1790442000',
]);

Example response

{
  "ok": 1,
  "id": 481
}

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: user_id"}The target user ID integer-converts below 1.
{"error":"missing or invalid parameter: date"}The date is absent or does not match the numeric YYYY-MM-DD pattern.
{"error":"missing or invalid parameter: clockin or clockout"}Both integer-converted times are zero.
{"error":"Clock-out time must be after clock-in time."}Both times are positive and clock-out is not later.
{"error":"This user is already clocked in. Please add a clock-out time before creating another session."}An incomplete candidate is created while the user already has an open session.
{"error":"This clocking period overlaps an existing entry for this user."}The candidate interval overlaps any existing interval, including an open interval. Adjacent boundaries are allowed.
{"error":"...","error_code":"earlier_clockins_open","earlier_sessions":[...]}A signed-in user starts a new open self session after one or more earlier sessions were left open.

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

Behaviour and edge cases

  • Multiple sessions for the same user/date are allowed when their epoch intervals do not overlap. One can begin exactly when another ends, and overnight sessions are supported.
  • A clock-out-only row is accepted when no open row blocks it. Negative nonzero times also pass the presence check; integrations should send only positive Unix seconds.
  • The special earlier-session response is produced only for an open session created for the signed-in user. General open/overlap validation still applies to other users.

Side effects

  • Inserts one user_clockins row with gross duration, current creation epochs for each supplied time, empty note/meta arrays, and source_type=1 (CRM).
  • Invalidates the user-clock-ins cache. It does not create generic audit history, set geolocation/difference/break fields, or verify that the user exists.

See it in Fieldmotion

CRM1

The header quick-clock widget and Users → Clock-ins create form call this route.

CRM2

The quick-clock menu and Clock-ins create dialog call this route. The quick flow can offer automatic repair when earlier_clockins_open is returned.

Related endpoints