Fieldmotion API Getting started

User clock-ins

Query mapped clock-in rows

POST /a/UserClockins_getDataTable

Query clock-in rows through CRM2’s named-field table helper, with an optional adjusted-only predicate.

When to use this endpoint

Use UserClockins_getDataTable for CRM2’s Clock-ins list, filtered ID discovery, or another trusted mapped-field query.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler performs no additional page or role-permission check.

The lookup and any write use the authenticated tenant; an ID from another tenant cannot be addressed through this call.

Parameters

ParameterTypeRequiredDescription
fieldsNative arrayYesRequested mapped keys. Valid keys are id, userID, user, date, clockIn, clockInCDate, clockInDiff, clockInNotes, clockOut, clockOutCDate, clockOutDiff, clockOutNotes, duration, flagged, flagNotes, clockInGeo, clockInGeoDist, clockOutGeo, clockOutGeoDist, meta, notes, userSignedOff, sourceType, and breaks. Unknown keys are ignored and id is always returned.
adjustedOnlyInteger-likeNoExact integer 1 restricts rows to a start/end adjustment of at least 60 seconds under the legacy predicate.
isTable / draw / start / length / limitInteger stringsNoShared table controls. Table mode defaults on with offset 0, length 10, and draw 0. Exact isTable=0 removes counts/paging unless positive limit is supplied.
orderBy / orderDesc / orderShared mapped orderingNoNamed ordering or DataTables fallback ordering. user sorts by joined user name.
searchValue / searchFieldString / mapped namesNoCase-insensitive substring search over selected/all mapped fields; user searches joined user names.
Mapped filters / advanceSearch / groupByShared scalar/array controlsNoAny mapped key can filter. Numeric values use equality, quoted scalars use substring matching, and arrays use IN. Advanced conditions/grouping are also accepted.
referenceDate / dateFrom / dateTo / timeRange* / offset*Shared date controlsNoSet referenceDate=date for relative stored-date filtering. The shared helper applies tenant/database timezone rules described by CRM2’s table widget.

Example request

$page = FM_api('UserClockins_getDataTable', [
	'fields' => ['id', 'user', 'date', 'clockIn', 'clockOut', 'breaks', 'flagged'],
	'adjustedOnly' => '1',
	'start' => '0',
	'length' => '25',
	'draw' => '4',
]);

Example response

{
  "data": [
    {
      "id": "481", "user": "18", "date": "2026-09-26",
      "clockIn": "1790413200", "clockOut": "1790442000",
      "breaks": "{\"total\":1800,\"breaks\":[]}", "flagged": "0"
    }
  ],
  "draw": 4,
  "recordsTotal": "91",
  "recordsFiltered": "3"
}

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: fields"}fields is absent. A JSON string is not decoded and can trigger a runtime type error.
{"error":"error in database query"}The generated select fails. Count-query failures are not separately translated.
Runtime warning or type errorA shared array-shaped option is supplied in an unsupported scalar form.

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

Behaviour and edge cases

  • A row qualifies for adjustedOnly=1 if a positive stored time differs by at least 60 seconds from a valid JSON geolocation timestamp, or if clockin_diff/clockout_diff is at least 60.
  • JSON columns are returned as stored JSON text, not decoded values. user and userID both return user_id; the former adds name search/sort behavior.
  • Computed UI columns such as net Total and Adjustment Reason are not server fields here. CRM2 derives them from the requested raw values.
  • Counts include every tenant clock-in and no role, department, or ownership filter is implicit.

See it in Fieldmotion

CRM1

CRM1 uses UserClockins_getDT, not this route.

CRM2

The list view requests visible/required mapped fields. Export setup also calls unpaged mode with fields=["id"] to discover IDs.

Related endpoints