Fieldmotion API Getting started

Tasks

Query the mapped Tasks table

POST /a/Tasks_getDataTable

Query active tasks through CRM2’s mapped table engine, including role-based customer scope and linked-job summaries.

When to use this endpoint

Use Tasks_getDataTable when reproducing CRM2’s Tasks list, calendar, Kanban, or export-selection query. It returns named mapped fields rather than CRM1’s positional arrays.

Authentication and permissions

The request must establish an authenticated tenant context with signed API credentials or a logged-in CRM session. This legacy handler uses the tenant database prefix without calling the normal login guard.

It performs no task, page, role, ownership, or privacy-permission check. Any visibility restriction described below comes from request filters or a specific server-side rule, not from a general Tasks permission check.

Parameters

ParameterTypeRequiredDescription
fieldsNative arrayYesMapped response keys. Unknown names are skipped and id is always added. Available mapped keys are id, type, details, resolution, userID/user, assignedDate, status, customerID/customer, createDate, lastEdited, createdBy, appId, editedId, privacy, meta, subject, dueDate, minutes, customValues, and metaPreviousUser. linkedJobs is appended to every returned row even though it is not a map key.
isTableInteger stringNoDefaults to table mode. Integer 0 returns only {"data":[...]} and allows optional limit.
draw / start / lengthInteger stringsNoTable draw counter, offset, and page size; defaults are 0, 0, and 10. The shared engine does not reject zero or negative lengths before SQL.
limitInteger stringNoPositive limit in non-table mode. Zero means no limit.
orderBy / orderDescMapped field / directionNoPreferred mapped sort field and direction. Field matching has a case-insensitive fallback; CRM sends asc or desc.
order[0][column] / order[0][dir]DataTables valuesNoPositional fallback ordering. The shared engine subtracts one from the column before indexing fields; exact desc selects descending.
searchValue / searchFieldString / string or arrayNoCase-insensitive mapped search. With no field, all searchable mapped fields are considered. Exact status maps New/Open/Closed/Archived names; an unknown status forces no rows.
appointmentIdNative array of picker objectsNoExact legacy wire key for filtering by linked jobs. Each object contributes its integer id; objects without a nonzero ID are ignored.
searchField=appointmentId / searchValueExact legacy key / integer-compatibleNoAlternative single linked-job ID filter used by direct search. The special keys are removed before mapped search processing.
dueStatusNative arrayNoOnly the exact one-item selection [0] filters to overdue tasks: due before current server time and status below 2. Other selections do not filter.
notesStringNoCase-insensitive substring in task-note text. The join can duplicate task rows and inflate recordsFiltered when several notes match.
customer / childJobAndAssetPicker object(s) / native arrayNoThe mapped customer filter accepts objects containing id. When childJobAndAsset includes 0, selected normal customers are expanded with their direct child customer IDs.
hasFilesNative arrayNoOne value: [0] requires a linked task file; [1] requires none. Two values apply no file filter.
referenceDate / dateFrom / dateToMapped field / day offsetsNoShared relative-date filtering. With a valid mapped date field and both offsets, builds an inclusive tenant-timezone window.
offsetFrom / offsetTo / timeRangeFrom / timeRangeToObjects / integer hoursNoShared timezone offsets and optional inclusive local-hour range for referenceDate.
advanceSearchNative arrayNoCRM2 condition objects using mapped columns and equal, contains, not-equal, greater, greater-or-equal, lesser, or lesser-or-equal comparisons.
groupByNative arrayNoMapped fields to add to SQL GROUP BY. Unknown fields are ignored.
Mapped field filtersScalar, array, or picker objectsNoMapped keys can be supplied directly. Text scalars use substring matching, numeric scalars use equality, arrays use IN, and user/customer accept picker objects.

Example request

$table = FM_api('Tasks_getDataTable', [
	'fields' => ['id', 'subject', 'status', 'customer', 'user', 'dueDate'],
	'draw' => '5',
	'start' => '0',
	'length' => '25',
	'searchField' => 'All',
	'searchValue' => 'access',
	'orderBy' => 'dueDate',
	'orderDesc' => 'asc',
]);

Example response

{
  "data": [
    {
      "id": "318",
      "subject": "Confirm access details",
      "status": "1",
      "dueDate": "2026-10-02 09:30:00",
      "user": {"id": "17"},
      "customer": {"id": "1042"},
      "linkedJobs": [{"jobID": 771, "jobRef": "FM-771"}]
    }
  ],
  "draw": 5,
  "recordsTotal": "250",
  "recordsFiltered": "1"
}

Mapped database values normally remain strings. Picker fields are objects, while each linkedJobs job ID is an integer.

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":"missing or invalid parameter: fields"}fields is absent.
{"error":"error in database query"}A constructed filter, empty linked-job result, invalid pagination value, or join combination produces invalid SQL.

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

Behaviour and edge cases

  • Soft-deleted tasks are excluded from data and counts. Table mode returns data, integer draw, and database scalar counts; non-table mode omits count metadata.
  • For a non-client-admin user, departmentBasedFilter on pageMain limits tasks to customers in the user’s departments, and accountManagerBasedFilter limits them to customers managed by that user. When both apply, their customer sets are intersected.
  • CRM2 constructs additional client-side conditions from viewCreatedAndAssignedOnlyByUser and viewPrivateTasks on pageTasksMain; the endpoint does not enforce those permissions itself. The disable-task-privacy tenant setting only hides privacy controls and does not change this query.
  • recordsTotal is the active tenant-wide count. recordsFiltered applies the effective filters but can overcount when joins create duplicate rows.
  • Linked jobs are queried after paging and appended regardless of requested fields. They are not ordered, deduplicated, or filtered for deleted job rows.
  • The hasFiles existence check does not apply a file deletion-status filter. Child-customer expansion also does not filter deleted child customer rows before adding their IDs.

See it in Fieldmotion

CRM1

No direct CRM1 caller was found. CRM1 uses Tasks_getDT and Tasks_getCalendar.

CRM2

Open Tasks in list, calendar, or Kanban view. The shared Task widget sends selected columns, page settings, filters, searches, sorting, and paging to Tasks_getDataTable; export first uses non-table mode to collect filtered IDs.

Related endpoints