Availability and leave
Soft-delete an availability event
/a/Availability_delete
Soft-delete an availability event
When to use this endpoint
Remove an event from active availability calculations and lists. This is distinct from keeping an active row with status=3 (cancelled). CRM2 may cancel an event through a separate mapped update before deleting it.
Authentication and permissions
Authenticate with signed API-key fields or a logged-in CRM session. Uses the authenticated tenant’s data. Requires pageAvailability_delete. 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
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Integer | Yes | Integer-converted ID of a non-deleted tenant event. Zero/missing or a deleted/nonexistent ID returns not found. The server does not restrict deletion to pending or cancelled events. |
Example request
$result = FM_api('Availability_delete', [
'id' => '1042',
]);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":"permission denied"} | The authenticated actor lacks the required page/action permission. |
{"error":"HR enhancements are disabled"} | The account has disabled HR enhancements. |
{"error":"availability event not found"} | The ID does not resolve to a non-deleted tenant event, including a repeated delete. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Retains the event row and sets deleted=1, Unix ddate, and Unix last_edited. It does not set status=3, clear approval attribution, or physically delete the row. Active lists, approved-event queries and leave usage exclude it.
- The CRM server does not enforce employee ownership, approver authority, pending-only state, or a browser confirmation token. Do not copy the mobile intermediary’s own-user/pending-only deletion contract onto this CRM route.
- The primary query is unchecked and no transaction covers the marker, balances, notices, or global push queue. Failed persistence can therefore be followed by cancellation messages and an ok response.
Side effects
- Sets the soft-delete/edit markers and requests availability_events cache invalidation.
- 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. - Sends a direct cancellation notice to the requester plus target users, updates recipient notices_latest, and queues global type-100 direct push. A user target is resolved without an active filter; company/department/role expansion uses active users. No unconditional email or configured notification rule is called by this handler.
See it in Fieldmotion
CRM1
No direct CRM1 caller for Availability_delete was found in the source search. The implemented management screen is CRM2’s Availability page.
CRM2
On Availability, use Delete and confirm the dialog; filter for Availability_delete. Bulk Delete first calls Availability_updateData with status=3 unless already cancelled, then calls delete once per event. These are separate requests, not an atomic batch; cancellation and deletion can produce separate notifications. The UI’s “permanently deleted” wording does not match the retained-row implementation.
Related endpoints
Availability_list: deleted rows no longer appear.Availability_decision: legacy status cancellation without deleting the row.Availability_updateData: the separate cancellation call used by CRM2 bulk delete.