Fieldmotion API Getting started

User work shifts

List user work shifts

POST /a/UserWorkShifts_getDataTable

List a user’s effective work-shift rows with synthetic IDs and DataTables-style counts.

When to use this endpoint

Use UserWorkShifts_getDataTable to populate CRM2’s Work Shifts tab or obtain the current positional IDs before detail/update/delete calls.

Authentication and permissions

The request must authenticate and HR enhancements must be enabled.

The endpoint does not enforce pageUserWorkShifts_view, Users permissions, target ownership, or active-user state.

Parameters

ParameterTypeRequiredDescription
userID / user_idInteger stringYesTarget tenant user. userID takes precedence and must integer-convert above zero.

Example request

$table = FM_api('UserWorkShifts_getDataTable', [
	'userID' => '18',
]);

Example response

{
  "data": [
    {
      "id": 18001,
      "userID": 18,
      "days": [1,2,3,4,5],
      "start": "08:30",
      "end": "17:00",
      "lunchDuration": 30,
      "lunchEarliest": "12:00",
      "lunchLatest": "14:00"
    }
  ],
  "recordsTotal": 1,
  "recordsFiltered": 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":"HR enhancements are disabled"}The tenant feature disables these APIs.
{"error":"missing or invalid parameter: userID"}Neither user alias resolves above zero.
{"error":"user does not exist"}No tenant user has that ID.

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

Behaviour and edge cases

  • This is not the shared SQL data-table helper. It ignores fields, search, filtering, ordering, draw, offset, and length; both counts always equal the full row count.
  • IDs are userID * 1000 + index + 1. They change after row reordering/deletion and should not be persisted externally.
  • Custom version-2 metadata is normalized. Legacy per-day work-hours arrays with index 0 are converted to one shift per valid day. Invalid nonempty stored data can normalize to no rows; absent/false/empty data uses company fallback.
  • Time output is HH:MM. Weekdays use 0 Sunday through 6 Saturday. A shift with no lunch reports duration zero and displays start/end as its lunch bounds.

See it in Fieldmotion

CRM1

No direct CRM1 caller was found.

CRM2

Open a user’s Work Shifts tab. The shared display widget calls this route without paging.

Related endpoints