Fieldmotion API Getting started

User clock-ins

Update one mapped clock-in field

POST /a/UserClockin_updateField

Apply one raw mapped clock-in value to one or more IDs without session-specific validation or dependent-field recalculation.

When to use this endpoint

Use UserClockin_updateField only for trusted mapped metadata updates. Use UserClockin_updateData for user/date/start/end changes.

Authentication and permissions

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

The handler checks neither page permissions nor row ownership.

Parameters

ParameterTypeRequiredDescription
id / idsInteger string or native arrayYesOne target ID or native list. id wins when both are supplied; values are integer-converted and missing rows are ignored.
fieldMapped keyYesOne of id, userID, user, date, clockIn, clockInCDate, clockInDiff, clockInNotes, clockOut, clockOutCDate, clockOutDiff, clockOutNotes, duration, flagged, flagNotes, clockInGeo, clockInGeoDist, clockOutGeo, clockOutGeoDist, meta, notes, userSignedOff, sourceType, or breaks.
valScalar or native JSON valueYesComplete replacement value. Native arrays/objects are encoded for JSON/quoted fields. Blank is accepted when present.

Example request

$result = FM_api('UserClockin_updateField', [
	'ids' => ['481', '482'],
	'field' => 'flagged',
	'val' => '1',
]);

Example response

{
  "ok": 1,
  "oldData": [
    {"id": "481", "flagged": "0"}
  ]
}

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: field"}field is absent.
{"error":"missing or invalid parameter: val"}val is absent.
{"error":"missing or invalid field"}The field is not in the clock-in map.
{"error":"missing or invalid parameter: id/ids"}Neither ID key is present.
{"error":"invalid date parameter: date"}The date value is not a strict SQL date.

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

Behaviour and edge cases

  • If all matching rows already have the requested value, or no IDs exist, the response is {"ok":"1","warning":"no change required"}. Note the string success value.
  • user and userID both map to user_id. JSON-path fields are not present in this map, so updates are direct column replacements.
  • The response’s oldData contains raw selected columns for rows found before the write; it can include unchanged rows.

Side effects

  • Updates matching rows, invalidates the user-clock-ins cache, and writes one generic audit event for the changed IDs.
  • Does not recalculate duration, validate overlap, advance a last-edited field, or synchronize any related state.

See it in Fieldmotion

CRM1

No direct CRM1 caller was found; CRM1 uses focused setters.

CRM2

The main table normally calls UserClockin_updateData. This route is used by generic/internal field workflows and tests.

Related endpoints