Fieldmotion API Getting started

Tasks

Retrieve task layout fields

POST /a/Task_getLayoutDetails

Retrieve caller-selected mapped task fields for CRM2 layout rendering.

When to use this endpoint

Use Task_getLayoutDetails to populate a configured Task layout. Unlike Task_getRequestedDetails, it requires an explicit field list and does not normally append linked-job data.

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 reads and writes use the authenticated tenant. CRM1 and CRM2 apply task visibility and editing permissions in their interfaces, but these handlers do not repeat those client-side rules.

Parameters

ParameterTypeRequiredDescription
fieldsNative array of stringsYesMapped field keys to return. Unknown keys are ignored and id is always added. Available keys are type, details, resolution, userID/user, assignedDate, status, customerID/customer, createDate, lastEdited, createdBy, appId, editedId, privacy, meta, subject, dueDate, minutes, customValues, and metaPreviousUser. Synthetic widgetTaskToJobLink is also supported.
id / idsInteger or native integer arrayNoRestricts rows by task ID. With neither parameter, all active tenant tasks matching other filters are returned.
Mapped field filtersScalar or native arrayNoAny mapped key supplied outside fields becomes an exact filter. Text comparison is trimmed/case-insensitive; numeric input is integer-coerced. Picker filters should use userID/customerID or native picker objects.
advanceSearchNative condition arrayNoShared mapped advanced-search expression. Invalid field names/conditions are ignored by the helper.
orderString or native arrayNoMapped field key(s), or objects with id and optional dir:"desc". No default order is applied.

Example request

$rows = FM_api('Task_getLayoutDetails', [
	'id' => '318',
	'fields' => ['id', 'subject', 'details', 'customer', 'user'],
]);

Example response

[
  {
    "id": "318",
    "subject": "Confirm access details",
    "details": "Confirm the site access details with the customer.",
    "customer": {"id": "1042"},
    "user": {"id": "17"}
  }
]

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"}The field list is absent.
[]No active row matches the supplied IDs/filters.

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

Behaviour and edge cases

  • Only active (deleted=0) tenant tasks are selected. There is no limit or pagination, so omitting an ID/filter can return the entire task table.
  • Unknown requested fields are omitted silently. Stored JSON is decoded for mapped JSON fields; database scalars otherwise retain their string representation.
  • Requesting widgetTaskToJobLink makes the handler fetch customerID internally and return widgetTaskToJobLink.customerID, removing the extra top-level customer field unless it was requested too.

See it in Fieldmotion

CRM1

No direct CRM1 caller was found; CRM1 uses the fixed Task_get response.

CRM2

Open Tasks in list, calendar, or Kanban view. CRM2’s configured Task Create/Update layouts use the mapped Task_createData, Task_getLayoutDetails, and Task_updateData routes.

Related endpoints