Fieldmotion API Getting started

User work shifts

Retrieve one user work shift

POST /a/UserWorkShift_getRequestedDetails

Resolve one synthetic work-shift ID to the current normalized row used by CRM2’s edit form.

When to use this endpoint

Use UserWorkShift_getRequestedDetails immediately before editing a row returned by UserWorkShifts_getDataTable.

Authentication and permissions

The request must authenticate and HR enhancements must be enabled.

The endpoint does not enforce Work Shifts view/edit permission or ownership of the encoded user.

Parameters

ParameterTypeRequiredDescription
idSynthetic integer stringYesEncoded as userID * 1000 + zeroBasedIndex + 1. Unlike update/delete, this route does not accept a user override.

Example request

$rows = FM_api('UserWorkShift_getRequestedDetails', [
	'id' => '18001',
]);

Example response

[
  {
    "id": 18001,
    "userID": 18,
    "days": [1,2,3,4,5],
    "start": "08:30",
    "end": "17:00",
    "lunchDuration": 30,
    "lunchEarliest": "12:00",
    "lunchLatest": "14:00"
  }
]

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: id"}The ID does not encode a positive user and nonnegative index.
{"error":"user does not exist"}The encoded user is absent.
{"error":"shift does not exist"}The decoded index is absent from the current effective rows.

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

Behaviour and edge cases

  • The response is an array containing one row, not a bare object. No fields selection is supported despite the route name.
  • If no custom meta.work_hours exists, the row may be synthesized from company work-day-start, work-day-end, and week-days-off settings.
  • Times are formatted HH:MM. Missing lunch duration becomes zero; lunch bounds then display the shift start/end defaults.

See it in Fieldmotion

CRM1

No direct CRM1 caller was found.

CRM2

Opening a Work Shifts row’s edit action uses this route through the shared display widget.

Related endpoints