Fieldmotion API Getting started

Tasks

Retrieve selected task fields

POST /a/Task_getRequestedDetails

Retrieve selected mapped task records and append each task’s linked job IDs and references.

When to use this endpoint

Use Task_getRequestedDetails for CRM2 task/job linking widgets or integrations that need mapped field names plus linked-job summaries.

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 stringsNoMapped keys to return; defaults to every key in the Task map. Unknown keys are ignored and id is always included. Keys are type, details, resolution, userID/user, assignedDate, status, customerID/customer, createDate, lastEdited, createdBy, appId, editedId, privacy, meta, subject, dueDate, minutes, customValues, and metaPreviousUser.
id / idsInteger or native integer arrayNoRestricts rows by task ID. Empty arrays add no ID filter.
Mapped field filtersScalar or native arrayNoAny mapped request key becomes an exact filter. Text is trimmed and compared case-insensitively; numeric values are integer-coerced.
advanceSearchNative condition arrayNoShared mapped advanced-search expression.
orderString or native arrayNoMapped sort key(s), or objects with id and optional descending direction. No default order is applied.

Example request

$rows = FM_api('Task_getRequestedDetails', [
	'ids' => ['318', '319'],
	'fields' => ['id', 'subject', 'dueDate', 'status'],
	'order' => [['id' => 'dueDate', 'dir' => 'desc']],
]);

Example response

[
  {
    "id": "319",
    "subject": "Confirm key collection",
    "dueDate": "2026-10-03 11:00:00",
    "status": "1",
    "linkedJobs": [{"jobID": 772, "jobRef": "JOB-772"}]
  },
  {
    "id": "318",
    "subject": "Confirm access details",
    "dueDate": "2026-10-02 09:30:00",
    "status": "1",
    "linkedJobs": []
  }
]

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.
[]No active task matches. Invalid/unknown requested fields are otherwise ignored rather than reported.

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 tenant tasks are returned. There is no limit or pagination; omitting IDs and filters can read all active tasks.
  • linkedJobs is appended even when not listed in fields. Links have integer jobID and database jobRef; the link query has no ordering and does not exclude deleted jobs.
  • Mapped JSON fields are decoded. Other database values normally remain strings.

See it in Fieldmotion

CRM1

No direct CRM1 caller was found. CRM1 uses Task_get and separate job-link routes.

CRM2

Task-to-job widgets and the Tasks module batch loader call Task_getRequestedDetails; filter the network panel while opening a Task’s linked Jobs control.

Related endpoints