Fieldmotion API Getting started

Availability and leave

Read normalized availability event records

POST /a/Availability_list

Read normalized availability event records

When to use this endpoint

Load one active event for an editor or retrieve a bounded set of raw event configurations by target/status/window. This is not a calculation of a user’s effective availability; use effective or timeline for precedence and working shifts.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. Uses the authenticated tenant’s data. Requires pageAvailability_view. Client administrators and full-access roles are allowed. Other roleless users are denied; signed API keys use the key owner’s role. These are page/action permissions, not an employee-ownership or HR-profile approver-list restriction.

Management calls reject accounts with features2.disableHREnhancements=1, returning HR enhancements are disabled. The helper reads the account’s current global feature value before falling back to session values. Browser permission checks are not server-side authorization.

Parameters

ParameterTypeRequiredDescription
idIntegerNoAdds equality only if intval is nonzero. Omitted, blank, zero, and nonnumeric text do not restrict the ID and can return a broad list; a negative converted ID does restrict the query.
from / toUnix secondsNoWhen present, from requires event end_e > from, and to requires start_e < to. Bounds are independent and integer-converted; there is no default window or start-before-end validation.
obj_typeStringNoNonblank exact target-type filter. This read does not apply the write endpoint’s allowlist.
obj_idIntegerNoPresent nonblank value adds exact integer-converted target ID, including zero. Used independently of obj_type.
statusIntegerNoPresent nonblank exact integer-converted status, including pending 0. Omitted returns every status, not only approved.

Example request

$events = FM_api('Availability_list', [
	'id' => '1042',
]);

Example response

[
  {
    "id": 1042,
    "obj_type": "user",
    "obj_id": 71,
    "event_type": "annual_leave",
    "availability": 0,
    "status": 0,
    "status_name": "pending",
    "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
  }
]

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.

Returns a bare array; missing/deleted IDs and no matches return [], not a not-found error. No total count or pagination cursor is supplied.

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":"permission denied"}The authenticated actor lacks the required page/action permission.
{"error":"HR enhancements are disabled"}The account has disabled HR enhancements.

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

Behaviour and edge cases

  • Reads only deleted=0 within the tenant. Orders by start_e descending then id descending, capped at 1000. There are no offset, page-size, field-projection, or custom-order parameters. Use getDataTable for paging.
  • Filters combine with AND; the from/to overlap is exclusive at the end boundary. Matching includes pending, rejected, cancelled, and approved rows unless a status filter is supplied.
  • The read does not apply company/role/department membership to derive which users are affected. It returns stored targets, not one expanded event per user.
  • No writes, leave recalculation, history entries, notifications or cache changes are performed.

See it in Fieldmotion

CRM1

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

CRM2

Open an Availability row or follow a notification link such as #pageAvailability/id=1042. The page loads Availability_list with id before opening the editor, and bulk actions also preflight each selected event through this route. The mobile app’s same-named route goes to m and lists only the current user’s events with different defaults; it is not this CRM tenant-wide read.

Related endpoints