Page and filter the Availability management table

When to use this endpoint

Drive the CRM2 Availability list with target labels, column/search filters, relative date windows and stable pagination. Use list for a compact one-ID read or getExportData for the full filtered export workflow.

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

Parameter	Type	Required	Description
`target / approved_by / name / notes`	String	No	Nonblank trimmed substring filters. target searches the resolved company/user/department/role label; approved_by searches the approver’s joined user name, not a numeric ID. target/approved_by/name lower-case the comparison; notes uses the database’s ordinary text comparison. Percent/underscore retain LIKE wildcard meaning.
`id / availability / status / all_day / paid`	Scalar, native array, or JSON array text	No	Exact IN filters. Values are integer-converted, deduplicated, and negatives removed. Zero is retained; malformed nonnumeric strings can become zero. A blank or normalized empty list imposes no restriction.
`obj_type / event_type`	Scalar, native array, or JSON array text	No	Trimmed exact IN values, with duplicates/empty strings removed. There is no write-style allowlist check; a blank/empty list imposes no restriction.
`referenceDate`	String	No	Only start_e or end_e selects a date-reference column. Takes effect only when dateFrom and dateTo are both supplied.
`dateFrom / dateTo`	Integer day offsets	Together	Relative to today in the account timezone (UTC if unset). Inclusive lower bound is local 00:00:00 plus dateFrom days; inclusive upper bound is local 23:59:59 plus dateTo days. This filters the chosen timestamp, not event overlap.
`searchValue / searchField`	String	No	Nonblank searchValue applies an additional substring search. searchField may be target, approved_by, name, notes, event_type or obj_type; omitted/unknown/All searches their union. Text case handling follows the corresponding field filter.
`start`	Integer	No	Offset, default 0, clamped to at least zero.
`length`	Integer	No	Page size, default 10. Values below 1 or above 1000 reset to 10 rather than returning all rows.
`orderBy`	String	No	Allowlisted key: id, target, approved_by, obj_type, event_type, name, availability, status, start_e, end_e, all_day, paid, notes, cdate, last_edited. Omitted/unknown uses start_e.
`orderDesc`	String	No	Case-insensitive asc chooses ascending; every other value/default is descending. The ID tie-breaker uses the same direction.

Example request

$page = FM_api('Availability_getDataTable', [
	'start' => '0',
	'length' => '20',
	'status' => json_encode([0]),
	'orderBy' => 'start_e',
	'orderDesc' => 'asc',
]);

Example response

{
  "data": [
    {
      "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,
      "target": "Example technician"
    }
  ],
  "recordsTotal": 3,
  "recordsFiltered": 1
}

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.

Each data row additionally has resolved target. Company is Company; missing user/department/role names fall back to User #ID, Department #ID, or Role #ID.

recordsTotal is the tenant’s total deleted=0 rows before request filters; recordsFiltered counts all matches before pagination. Both are integers. No draw value is echoed. The response’s approved_by remains the numeric actor ID even though its filter/order uses the joined name.

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.

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

Behaviour and edge cases

All filters combine with AND, and searchValue adds another condition. Zero-status filters mean pending rather than “all”; an empty selection means no filter.
Only undeleted event rows are returned, but joined target/approver users are not restricted to active users. This read does not implement role-level or department-level visibility.
Every page returns the full normalized event shape plus target. Generic fields/advanceSearch/groupBy controls are not consumed, and from/to overlap filters from Availability_list are not aliases for referenceDate/dateFrom/dateTo.
No rows means data=[] with the corresponding counts. The read has no write, notification, cache-invalidation, or leave-recalculation side effects.

See it in Fieldmotion

CRM1

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

CRM2

Open Availability and change a column filter, search field, date-reference range, sorting or page. The shared display widget uses prefix/prefixes Availability to call Availability_getDataTable. It is a custom table endpoint, not the generic mapped details response.

Related endpoints

Availability_list: one-ID normalized read without target enrichment.
Availability_getExportData: enumerate/export all matches rather than the visible page.
Availability_import: ingest edited spreadsheet rows.