Fieldmotion API Getting started

Availability and leave

Load approved availability events for scheduler input

POST /a/Availability_forScheduler

Load approved availability events for scheduler input

When to use this endpoint

Retrieve ranked event inputs for the scheduler/solver. This endpoint does not decide a single available flag and does not itself schedule, move or create jobs.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. Uses the authenticated tenant’s data. This scheduler/job helper has no extra Availability-management page or role-permission check.

There is no per-user/department visibility or active-user permission filter in this CRM read. Existing target memberships come from the tenant users table; do not pass outsourced-user tokens as local IDs.

Unlike management routes, disabled HR enhancements do not return a feature error here. The helper applies the endpoint-specific empty/available fallback described below after validating request formats and the window.

Parameters

ParameterTypeRequiredDescription
user_idsNative array or JSON array textNoDefaults to an empty array, which returns an empty result. A scalar string is JSON-decoded and must become an array. Pass actual positive tenant user IDs; element values are integer-converted, without a public existence/positivity validation error.
start_e / end_eUnix secondsYesInteger-converted positive start and strictly later end. Epoch milliseconds are not converted automatically.
from / toUnix secondsAliasesUsed only when start_e/end_e are null or omitted, respectively. A present blank/zero primary field takes precedence and fails validation; a null primary value allows its alias.

Example request

$result = FM_api('Availability_forScheduler', [
	'user_ids' => json_encode([71]),
	'start_e' => '1793005200',
	'end_e' => '1793034000',
]);

Example response

{
  "71": [
    {
      "id": 1042,
      "obj_type": "user",
      "obj_id": 71,
      "event_type": "annual_leave",
      "availability": 0,
      "status": 1,
      "status_name": "approved",
      "name": "Annual leave",
      "start_e": 1793005200,
      "end_e": 1793034000,
      "all_day": 0,
      "paid": 1,
      "requested_by": 71,
      "approved_by": 0,
      "approved_at": 0,
      "notes": "Family leave",
      "meta": [],
      "cdate": 1792584000,
      "last_edited": 1792584000,
      "created_by": 71,
      "specificity": 4
    }
  ]
}

Normalized event objects contain id, obj_type, obj_id, event_type, availability, status, derived status_name, name, start_e, end_e, all_day, paid, requested_by, approved_by, approved_at, notes, decoded meta, cdate, last_edited, and created_by. Numeric fields are integers, unlike raw database rows. Invalid/non-array metadata becomes []; deleted/ddate are not exposed by the normalizer.

The top-level map is keyed by resolved tenant user ID; each value is a ranked array of real normalized events with an additional integer specificity. Existing users with no matching events have empty arrays. Unknown IDs are omitted, and no resolved users or disabled HR returns [].

Available overrides (availability=1) are included as well as unavailable events. Events retain their full stored start/end times, not clipped endpoints. There is no synthetic work_shift row, available flag or total count.

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: user_ids"}A non-array input does not JSON-decode to an array.
{"error":"missing or invalid time window"}Integer-converted start is below one or end is not later than start. These request checks run before the disabled-HR fallback.

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

Behaviour and edge cases

  • Only approved (status=1), deleted=0 events overlapping the window are considered: start_e < requested end and end_e > requested start. Company target 0 affects every resolved user, then matching role and any department, then user-specific targets. Precedence is descending specificity (user 4, department 3, role 2, company 1), then cdate, then last_edited, then event ID, all descending. This is creation-time-first within a specificity level, not simply latest edit wins.
  • User membership is resolved from users without an active/deleted-user restriction. Duplicate requested IDs are integer-normalized and deduplicated by the membership helper. Company/role/department entries are expanded to every matching requested user, so the same event ID can appear under several keys.
  • This read does not apply work-shift coverage or merge/clip event ranges. The solver may combine these events with user shift data obtained separately.
  • No pagination or result/window-size cap is present. The handler has no writes, history, notifications, cache invalidation or balance recalculation.

See it in Fieldmotion

CRM1

No direct CRM1 caller for Availability_forScheduler was found in the source search. The implemented management screen is CRM2’s Availability page.

CRM2

Open the Scheduler and load its date range/users. widgetScheduler requests Availability_forScheduler after loading user data and passes the returned map into its scheduling setup. The browser skips this request when disableHREnhancements is enabled.

Related endpoints