Update a user work shift · Fieldmotion API

When to use this endpoint

Use UserWorkShift_updateData for CRM2’s Work Shifts edit form. The synthetic ID must come from a fresh list/detail response.

Authentication and permissions

The request must authenticate and HR enhancements must be enabled.

The handler does not enforce pageUserWorkShifts_edit, Users edit permission, ownership, or active-user state.

Parameters

Parameter	Type	Required	Description
`id`	Synthetic integer string	Yes	Encodes the default target user and row index. IDs are positional rather than persistent.
`userID / user_id`	Integer string	No	Optional target-user override. The index still comes from `id`, so a mismatched user edits that index on another user.
`days`	Array/JSON/comma text/scalar	No	Replacement weekdays when supplied. Omission preserves the existing row. Valid values are unique integers `0..6`.
`start / end`	HH:MM text or numeric seconds	No	Replacement bounds when supplied; omission preserves existing formatted values. Equal bounds are invalid and end-before-start means overnight.
`lunchDuration`	Integer minutes	No	Replacement duration. A positive value requires valid window bounds after merge; zero removes all stored lunch fields. The helper recognizes `lunch_duration`, but the existing row’s camel-case key wins after merge, so use camel-case when updating.
`lunchEarliest / lunchLatest`	HH:MM text or numeric seconds	No	Replacement lunch window bounds. Snake-case aliases are similarly shadowed by the merged existing camel-case keys; use these names for updates.

Example request

$result = FM_api('UserWorkShift_updateData', [
	'id' => '18001',
	'userID' => '18',
	'end' => '17:30',
	'lunchDuration' => '45',
	'lunchEarliest' => '12:00',
	'lunchLatest' => '14:00',
]);

Example response

{
  "ok": 1
}

Errors and unusual responses

Response	Condition
`{"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"}`	No positive target user can be resolved.
`{"error":"missing or invalid parameter: id"}`	The ID is below one or decodes to a negative index.
`{"error":"user does not exist"}`	The selected user is absent.
`{"error":"shift does not exist"}`	The decoded index is absent.
`{"error":"invalid shift start/end time"}`	A resulting bound is invalid/equal.
`{"error":"each shift must include at least one day"}`	A resulting row has no valid weekdays.
`{"error":"invalid lunch time"} / {"error":"lunch window must fit within the shift"}`	A positive lunch has invalid bounds or does not fit the wrapped shift.

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 mismatched user override redirects the edit. The implementation merges into the override user’s row at the index decoded from id. Keep userID consistent with the encoded/listed row.

Updates are partial at the row level because request fields are merged over the listed row, but the entire schedule is then reparsed, validated, and replaced.
Editing a company-fallback row when the user has no custom schedule saves the full fallback as a user-specific custom schedule.
Multiple resulting shifts may overlap or repeat weekdays. Numeric time values mean seconds after midnight; text parsing accepts trailing characters after a valid HH:MM prefix.

Side effects

Replaces meta.work_hours, preserves other user metadata, sets current last_edited and edited_uuid="UserWorkShift", and invalidates the users cache.
Does not write generic audit history. Concurrent metadata edits can be lost because the complete user meta JSON is read and replaced.

See it in Fieldmotion

CRM1

No direct CRM1 caller was found.

CRM2

Submit the edit form on a user’s Work Shifts tab.

Related endpoints

UserWorkShift_getRequestedDetails supplies the edit form row.
UserWorkShift_createData appends another row.