Fieldmotion API Getting started

Availability and leave

Change a legacy availability request status

POST /a/Availability_decision

Change a legacy availability request status

When to use this endpoint

Apply an approved, rejected, or cancelled status with the legacy transition-notice workflow. For the current CRM2 action buttons, the actual route is updateData rather than this focused endpoint.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. Uses the authenticated tenant’s data. Requires pageAvailability_edit. 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
idIntegerYesInteger-converted non-deleted tenant event ID; missing defaults to zero and produces not-found after status validation.
statusIntegerYesInteger-converted 1 approved, 2 rejected, or 3 cancelled. Defaults to -1; pending 0 is not accepted here. There is no restriction to transitions from pending.

Example request

$result = FM_api('Availability_decision', [
	'id' => '1042',
	'status' => '1',
]);

Example response

{
  "ok": 1,
  "event": {
    "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": 72,
    "approved_at": 1792584060,
    "notes": "Family leave",
    "meta": [],
    "cdate": 1792584000,
    "last_edited": 1792584060,
    "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.

No separate id property is added to the outer envelope. Repeated approval can refresh approved_by/approved_at even when status already equals 1; the response is not an idempotency acknowledgement. A failed post-save re-read can leave event=null with saved=1 and a warning, rather than changing the committed decision into a replayable error.

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.
{"error":"invalid status"}Integer-converted status is not 1, 2, or 3; checked before event lookup.
{"error":"availability event not found"}ID does not resolve to a non-deleted tenant event.
{"error":"Unable to save availability event"}The primary event write failed; dependent recalculation and notices are not run.

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 handler accepts any currently active event and any of the three status values. It does not verify manager/approver authority, original requester, or the UI’s pending-only restriction.
  • Always advances last_edited. Every approval stamps the current actor/time; rejection/cancellation do not erase old approval attribution. The transition notice is sent only when the stored status changes, so repeated approval updates attribution without another transition notice.
  • The primary row write is checked before recalculation and notifications; a failed write returns an error rather than ok=1. Approval stamps are still refreshed on repeated approval, so this is not an idempotent approval acknowledgement.
  • The primary write is checked before dependent work. After saving, failed recalculation or notification work retains the normal success fields and adds saved=1 and warning. Do not repeat the write to repair a follow-up; re-read the event and investigate balances/notification history. The event, history, balances and external queues are not one atomic transaction.

Side effects

  • Updates status, Unix edit timestamp and approval fields where applicable; invalidates availability_events cache. No Core_log history call is made by this handler.
  • When an old or new event is approved annual leave, the helper recalculates affected users’ stored annual-leave usage for touched years, using current company/department/role/user membership. Each account-local date touched counts as one whole day except dates in week-days-off (0 Sunday through 6 Saturday). Partial dates count as full days, year boundaries are split, and calendar arithmetic preserves DST dates. Overlapping leave events contribute separately; balances may become negative. Supported recalculation years are the server’s current year minus five through plus ten.
  • The legacy transition helper creates tenant notices, advances recipients’ users.meta.notices_latest, and queues direct push work in global cron type 100. A new pending request uses configured HR-profile leave approvers, otherwise managers, otherwise active users whose ID is the tenant owner or whose permissions text is nonblank; the requester is excluded from that creation notice. A status change notifies the requester plus target users. It does not send unconditional email copies or run configured notification rules.
  • Decision notification subject dates use the server date with the account date-format setting after collapsing repeated format letters. The subject says “Annual Leave request” even for other availability event types.

See it in Fieldmotion

CRM1

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

CRM2

No direct Availability_decision caller was found in the current CRM2 page. Availability action buttons and bulk actions use Availability_updateData; that path uses configured rules instead of these direct legacy transition notices.

Related endpoints