Fieldmotion API Getting started

User accounts and profiles

Read a user’s work-shift configuration

POST /a/User_getWorkShifts

Read normalized custom shifts alongside the account’s fallback working hours.

When to use this endpoint

Use when a client needs to distinguish a custom schedule from inherited account settings. This is configuration, not a leave/event availability calculation.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. Session requests use the dispatcher’s CSRF protection when configured.

Configured TeamAccess authorizes the primary target ID before this handler.

Self reads are allowed; reading another user’s shifts requires explicit Users View. HR enhancements must be enabled.

Parameters

ParameterTypeRequiredDescription
idInteger stringYesOne tenant user ID. Integer conversion is performed by the handler; no pagination or ordering applies.

Example request

$result = FM_api('User_getWorkShifts', [
	'id'=>'1042',
]);

Example response

{
  "id": 1042,
  "has_custom": 0,
  "work_hours": null,
  "fallback": {
    "version": 2,
    "shifts": [
      {
        "days": [
          1,
          2,
          3,
          4,
          5
        ],
        "start": 30600,
        "end": 61200,
        "lunch_earliest": 42300,
        "lunch_latest": 49500,
        "lunch_duration": 3600
      }
    ],
    "is_default": 1
  }
}

Illustrative fallback for Monday–Friday, 08:30–17:00 settings. Actual days/times depend on account settings.

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: id"}id converts below 1.
{"error": "HR enhancements are disabled"}The account disables HR enhancements.
{"error": "user does not exist"}No tenant user row.

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

Behaviour and edge cases

  • has_custom tests whether meta contains work_hours, even if that saved value is null or malformed. With no key, work_hours is null; fallback is always returned separately.
  • Normalized version 2 uses shifts containing days (0–6, Sunday–Saturday), start/end seconds after local midnight and optional lunch_earliest/lunch_latest/lunch_duration in seconds. end below start represents overnight work. Read normalization skips unusable entries and clamps time bounds; it does not rewrite storage.
  • Legacy per-day [start-hour,duration-hour] entries are normalized to version 2. An unusable custom value normalizes to an empty shifts list rather than silently substituting fallback in this reader.
  • Fallback comes from work-day-start/work-day-end in minutes (defaults 510/1020 when falsy), and week-days-off. It uses remaining weekday indices and, for a forward daytime span, a one-hour lunch window around the midpoint. The response does not include a timezone field.
  • disableHREnhancements is read from the current account feature settings before user lookup. No active-user or parent-membership filter is added.

Side effects

  • Reads data without changing business records, edit markers, activity history or notifications. Shared setting reads can populate their normal settings cache.

See it in Fieldmotion

CRM1

No direct production caller was found in CRM1. Scheduler configuration consumes related User helper output.

CRM2

No direct call to this exact reader was found. CRM2’s HR profile page receives the same custom/fallback shapes inside User_getHrProfile; scheduling uses Users_getSchedulerInfo.

Related endpoints