Fieldmotion API Getting started

Availability and leave

Export filtered availability records in two stages

POST /a/Availability_getExportData

Export filtered availability records in two stages

When to use this endpoint

First enumerate all event IDs matching the current list filters, then fetch selected export fields in batches using those IDs. The returned JSON is converted to CSV by the CRM2 export widget; this endpoint does not stream a CSV file.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. Uses the authenticated tenant’s data. Requires both pageAvailability_view and pageMain_exportTableData. 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
_idsLiteral 1 or JSON array textYesExact integer/string 1 enumerates matching IDs. A JSON-encoded nonempty array selects the data stage; even a one-ID export must be an array such as "[1042]", not literal 1. Native arrays are not decoded by this handler. JSON objects, native arrays, nested values and nonnumeric ID elements return a validation error.
fieldsJSON array textFor data stageNonempty ordered list drawn from id, target, obj_type, obj_id, event_type, name, availability, status, approved_by, start_e, end_e, all_day, paid, requested_by, notes. Unlike table/read helpers, this must be JSON text, not a native array. JSON objects (even numeric-keyed ones), nested lists and non-string field elements are rejected before SQL construction.
target / approved_by / name / notesStringID stage onlyNonblank 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. These request filters are applied when _ids=1, not when explicit IDs are fetched.
id / availability / status / all_day / paidScalar, native array, or JSON array textID stage onlyExact 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. These request filters are applied when _ids=1, not when explicit IDs are fetched.
obj_type / event_typeScalar, native array, or JSON array textID stage onlyTrimmed exact IN values, with duplicates/empty strings removed. There is no write-style allowlist check; a blank/empty list imposes no restriction. These request filters are applied when _ids=1, not when explicit IDs are fetched.
referenceDateStringID stage onlyOnly start_e or end_e selects a date-reference column. Takes effect only when dateFrom and dateTo are both supplied. These request filters are applied when _ids=1, not when explicit IDs are fetched.
dateFrom / dateToInteger day offsetsID stage onlyRelative 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. These request filters are applied when _ids=1, not when explicit IDs are fetched.
searchValue / searchFieldStringID stage onlyNonblank 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. These request filters are applied when _ids=1, not when explicit IDs are fetched.

Example request

$selection = FM_api('Availability_getExportData', [
	'_ids' => '1',
	'status' => json_encode([0]),
]);

$rows = FM_api('Availability_getExportData', [
	'_ids' => json_encode([1042]),
	'fields' => json_encode(['id', 'target', 'approved_by', 'start_e']),
]);

Example response

[
	{"availability_id":"1042","f0":"1042","f1":"Example technician","f2":"","f3":"1793005200"}
]

The ID stage returns {"ids":[1042,...]} with integer IDs. The data stage returns database rows with availability_id plus positional f0, f1, etc. Numeric database values can be strings; field names are not response keys.

Exported approved_by is the joined approver name, or empty when missing, rather than the numeric ID returned by list/getDataTable. There is no status_name, meta, leave_days, cdate or last_edited export field in this map.

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":"missing or invalid parameter: _ids"}No _ids key is supplied; checked before login.
{"error":"HR enhancements are disabled"}The account has disabled HR enhancements.
{"error":"_ids should be a JSON array of numbers"}Data-stage _ids is not nonempty JSON list text containing scalar numbers/numeric strings, including native arrays, JSON objects, nested values and [].
{"error":"fields should be an array of requested field names"}Selected positive IDs remain, but fields is not nonempty JSON list text containing only string field names.
{"error":"unknown field name: FIELD"}A selected field is not in the export allowlist.

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

Behaviour and edge cases

  • Both stages exclude deleted events and order by start_e descending then id descending. There is no endpoint pagination/size cap; caller-controlled batching is needed for the data stage.
  • The ID stage applies the same filters as getDataTable without its paging or caller-selected sort. The data stage uses only the selected positive integer-converted IDs and deleted=0; it does not reapply other filter parameters or preserve requested ID order.
  • If _ids decodes to a nonempty array but every entry becomes zero/negative, returns [] before validating fields. Missing/deleted selected IDs are omitted. Duplicated input IDs do not duplicate rows through SQL IN.
  • No writes, recalculation, notifications, or cache changes are performed.

See it in Fieldmotion

CRM1

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

CRM2

In Availability, choose Export. The page first calls Availability_getExportData with _ids=1 and active list filters, then widgetExportCRM2 requests selected fields and batches from that ID list. Filter for the route to observe both response shapes.

Related endpoints