Fieldmotion API Getting started

Customers

List customer jobs for a data table

POST /a/Customer_getAppointmentsDT

Populate the customer Jobs table with direct, subsidiary, location, and asset jobs plus file, invoice, and report indicators.

When to use this endpoint

Use Customer_getAppointmentsDT for the paged Jobs panel on a customer record. It combines jobs addressed directly to that customer with jobs addressed to the customer’s locations and assets; showChild can also add jobs addressed directly to descendants.

Use Customer_listJobs instead when only the IDs of non-deleted jobs addressed directly to the customer are needed.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler performs no additional page or role-permission check.

The lookup and any write use the authenticated tenant; an ID from another tenant cannot be addressed through this call.

Parameters

ParameterTypeRequiredDescription
customer_idInteger stringYesCustomer ID. The handler accepts 0 as well as positive IDs and does not verify that the customer exists.
startInteger stringYesZero-based row offset. A negative value is rejected.
lengthInteger stringYesPage size. A negative value is rejected; 0 produces an empty page.
drawInteger stringNoDataTables request counter copied to the response; defaults to 0.
order[0][column]Integer stringNoSort column: 1 date, 2 job reference, 3 assigned user name, 4 form name, or 6 completion state. Other values use date.
order[0][dir]StringNoOnly exact asc selects ascending order; omitted and all other values select descending order. Job ID is the secondary sort.
showChildInteger stringNoA non-zero value adds direct customer jobs whose denormalized parent1, parent2, or parent3 equals this customer. It does not add location or asset jobs belonging to descendants.
search[value]StringNoSubstring search across job reference, assigned-user name, matching asset name/code, form values, subform values, and form name.
daysFromInteger stringNoRelative-day lower bound. The endpoint converts the server-calculated date to tenant-local midnight and requires the job time to be strictly later than it.
daysToInteger stringNoRelative-day upper bound. The endpoint converts midnight after the requested day to tenant epoch time and requires the job time to be strictly earlier. May be supplied independently of daysFrom.
user_idInteger stringNoExact assigned-user filter. Zero and blank values do not filter.
statusInteger stringNoExact is_complete filter. Blank and -1 mean all states; 0 is a real filter.
job_refStringNoExact trimmed job-reference filter.
form_nameStringNoCase-insensitive substring match against form names. No matching form forces an empty result.
job_typeString, array, or JSON arrayNoA positive ID selects that type; 0 selects zero/NULL types; text matches type names. Arrays can combine positive IDs and 0; negative IDs exclude their absolute type while retaining NULL types.

Example request

$jobs = FM_api('Customer_getAppointmentsDT', [
	'customer_id' => '1088',
	'start' => '0',
	'length' => '25',
	'draw' => '3',
	'order' => [['column' => '1', 'dir' => 'desc']],
	'showChild' => '1',
	'status' => '0',
	'job_type' => json_encode([0, 12, -18]),
]);

Example response

{
  "draw": 3,
  "recordsTotal": "1",
  "recordsFiltered": "1",
  "data": [
    ["7204", "2026-09-24 10:30:00", "JOB-7204", ["36"], "Service Visit", "14", "0", "Repair", 1, "1088", "0", "Northwind Belfast", "Access via rear gate", [{"to_id":"902","type_num":"3"}], 1, "Investigate intermittent fault"]
  ]
}

Each positional row is: job ID, tenant-local job date/time, job reference, one-element user-ID array, form name, form ID, completion value, job-type name, has-files flag, target ID, target type, joined customer name, HTML-escaped internal notes, linked invoice records, PDF/report-sent flag, and raw job notes.

recordsTotal and recordsFiltered are calculated from the same complete filter, so neither is an unfiltered customer-job total.

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: start"}start is absent.
{"error":"missing or invalid parameter: customer_id"}customer_id is absent or negative.
{"error":"missing or invalid parameter: length"}length is absent or negative.

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 non-deleted jobs are returned. Non-deleted work areas are included when their customer_type=1 and customer_id equals the requested customer. Assets are included when the customer owns them or they are located directly with the customer, and deleted assets are excluded.
  • showChild relies on the three stored parent slots, so its hierarchy depth is limited to those fields. The endpoint does not independently traverse the customer tree.
  • The customer-name join is always made against the numeric target ID. On asset- and location-targeted rows, that field is not a reliable description of the actual target.
  • The files flag counts non-deleted job files. Invoice links include only non-deleted invoices related through relationship types 3 or 4.
  • Internal notes are HTML-escaped; ordinary job notes are returned raw. Database IDs and most stored flags remain strings.

See it in Fieldmotion

CRM1

Open Customers, open a customer, and select Jobs. Filter Network requests for Customer_getAppointmentsDT. The page supplies its date-range tenant settings (customer-jobs-days-from and customer-jobs-days-to) and its user, status, job-reference, form, type, search, and child-customer controls.

CRM2

A source search found no CRM2 caller for this endpoint. CRM2 customer workflows use other job-list calls rather than this CRM1 positional table contract.

Related endpoints