Fieldmotion API Getting started

Tasks

Query the legacy Tasks table

POST /a/Tasks_getDT

Page, filter, and sort the positional task rows used by CRM1’s legacy Tasks table.

When to use this endpoint

Use Tasks_getDT only for the CRM1 DataTables contract. For named mapped fields and CRM2 filters, use Tasks_getDataTable.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler calls the normal login guard but performs no additional task, page, role, ownership, or privacy-permission check.

All rows come from the authenticated tenant. Unless the page says otherwise, IDs, creator, assignee, and privacy do not restrict the result at handler level.

Parameters

ParameterTypeRequiredDescription
lengthPositive integer stringYesPage size. Values below 1 are rejected. There is no maximum enforced by the handler.
startInteger stringNoRow offset; defaults to 0.
drawInteger stringNoDataTables draw counter copied to the response; defaults to 0.
order[0][column]Integer stringNoSupported positions are 1 created date, 2 assigned-user name, 6 due date, and 8 status. Other values sort by created date.
order[0][dir]StringNoExact desc selects descending; every other value selects ascending.
search[value]StringNoTrimmed, lower-cased search text. It is applied only when search[fields] is also a string longer than two characters.
search[fields]JSON array stringConditionalAny of all, customer_name, details, subject, resolution, cdate, due_date, and users_name. Date fields are searched only when the term contains digits, slash, hyphen, or spaces.
daysFilterInteger stringNoTruthy enables created-date filters.
dateFrom / dateToDate stringsConditionalWhen daysFilter is enabled and dateFrom exists, created date is inclusive from dateFrom through dateTo 23:59:59. The handler reads dateTo without separately checking it.
daysFrom / daysToInteger day offsetsConditionalAlternative created-date window relative to the current server timestamp. The lower bound is inclusive; the upper bound is the start of daysTo + 1. Both date-window forms are combined when both are supplied.
user_idInteger-compatibleNoNonzero assigned-user ID. Zero cannot explicitly select unassigned rows.
f_customerStringNoCase-insensitive customer-name substring.
statusInteger-compatible or blankNoExact status when nonblank. If absent or blank, Archived status 3 is excluded by the default status<3 filter.
task_idInteger-compatibleNoNonzero exact task ID.
viewEveryoneInteger stringNoFalsy restricts rows to tasks assigned to or created by the caller. Truthy also permits public tasks; with view_private=1 it removes this visibility filter entirely.
view_privateInteger stringNoOnly consulted with truthy viewEveryone. The handler does not verify the caller has permission to request it.
searchTypeInteger-compatibleNoNonzero exact task-type ID.

Example request

$table = FM_api('Tasks_getDT', [
	'draw' => '4',
	'start' => '0',
	'length' => '25',
	'status' => '1',
	'viewEveryone' => '1',
	'view_private' => '0',
	'search' => [
		'value' => 'access',
		'fields' => json_encode(['subject', 'details']),
	],
]);

Example response

{
  "draw": 4,
  "recordsTotal": "250",
  "recordsFiltered": "1",
  "data": [
    ["318", "2026-09-27 14:05:00", "17", "2026-09-27 14:05:00", ["1042", "Northwind Service Centre"], "Confirm access details", "2026-10-02 09:30:00", "", "1", "0", 0, "1", 2, [[771, "FM-771"]], "Customer follow-up"]
  ]
}

Row positions are: ID, created date, assignee ID, assigned date, [customer ID, active customer name], subject, due date, resolution, status, time spent, constant integer 0, privacy, linked-file count, [job ID, job reference] pairs, and task-type name.

Counts and most row scalars are database strings. File count and linked job IDs are integers.

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: length"}length is absent, zero, negative, or not integer-compatible. This guard runs before the login check.
{"error":"search fields empty"}A nonempty search is paired with a search[fields] string that JSON-decodes to null.
Response without a data keyNo rows match. The handler creates data only while iterating rows, rather than returning an explicit empty array.

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. recordsTotal counts every active tenant task before visibility and other filters; recordsFiltered applies the effective filters.
  • Customer names are re-read with deleted=0; a task linked to a deleted customer returns its customer ID with a null name.
  • Linked-file counts and linked jobs are not filtered for deletion, ordered, or deduplicated. The selected details column is not included in the positional response.

See it in Fieldmotion

CRM1

Open Tasks in list view. Paging, ordering, date controls, status/user/customer/type filters, “view everyone”, and the search-field selector feed Tasks_getDT. CRM1 sends view_private=1 for the tenant parent or a user with CRM access bit 1024; the endpoint itself does not verify that decision.

CRM2

No direct CRM2 caller was found. CRM2’s Tasks module uses Tasks_getDataTable.

Related endpoints