Fieldmotion API Getting started

Customers

List customer job financials

POST /a/Customer_financialsGetDT

Return paged job-level labour, mileage, stock, price, tax, and profit figures for the customer Financials tab.

When to use this endpoint

Use Customer_financialsGetDT when reproducing the CRM1 customer Financials table and its job, department, status, date, and text filters.

Use Customer_financialsExport for the matching unpaged CSV workflow.

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
cidInteger stringYesPositive customer ID. The endpoint verifies that a row with this ID exists, but does not require it to be active or non-deleted.
startInteger stringYesZero-based row offset; only presence is validated.
lengthInteger stringNoPage size; defaults to 0, which returns no rows while still calculating counts.
drawInteger stringNoDataTables request counter; defaults to 0.
order[0][column]Integer stringNo0 job ID, 1 contract, 2 job date, 3 labour, 4 mileage, 5 stock, 6 total costs, 7 net, 8 gross, 9 tax, or 10 profit.
order[0][dir]StringNoExact desc selects descending; other values and omission select ascending.
search[value]StringNoA numeric value can match exact job ID; every value also substring-matches contract name or joined customer name.
dateFromDate/time stringNoInclusive tenant-local lower bound converted to epoch time. When present, dateTo is also consumed.
dateToDate stringWith dateFromInclusive tenant-local upper bound through 23:59:59.
daysFromInteger stringNoRelative-day lower bound from server-calculated today, converted to tenant-local midnight and applied inclusively. When present, daysTo is also consumed.
daysToInteger stringWith daysFromRelative-day upper bound. Midnight after that day is an exclusive boundary.
jobTypeInteger stringNoExact job type ID. Zero and blank do not filter.
department_idInteger stringNoExact department ID. Zero and blank do not filter.
status_idInteger stringNoExact is_complete value. Blank means all; 0 is a real filter.

Example request

$financials = FM_api('Customer_financialsGetDT', [
	'cid' => '1088',
	'start' => '0',
	'length' => '25',
	'draw' => '7',
	'order' => [['column' => '2', 'dir' => 'desc']],
	'search' => ['value' => 'Annual'],
	'dateFrom' => '2026-09-01',
	'dateTo' => '2026-09-30',
	'status_id' => '1',
]);

Example response

{
  "draw": 7,
  "recordsTotal": 840,
  "recordsFiltered": 1,
  "data": [
    ["7204", "Annual Maintenance", "2026-09-24 10:30:00", "80.00", "12.00", "45.00", ["2.0","18"], "137.00", "300.00", "369.00", "69.00", "163.00"]
  ]
}

Each positional row is job ID, contract name, tenant-local job date/time, labour cost, mileage cost, stock cost, [hours, miles], total costs, net price, gross price, tax, and profit.

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: cid"}cid is absent or converts to less than 1.
{"error":"customer does not exist"}No customer row has the supplied ID.

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 direct-customer jobs (customer_type=0) are considered. The legacy customer predicate is exactly parent_id=cid OR (customer_id=cid AND parent_id IN (0,-1)); it does not simply mean every job whose customer ID equals cid.
  • recordsTotal counts every meeting in the tenant, including unrelated and deleted rows. recordsFiltered applies the customer and request filters.
  • Total costs substitute zero for NULL components. Profit uses direct arithmetic without those substitutions, so it can be NULL when a component cost is NULL.
  • The endpoint reads financial fields already stored on each job; it does not recalculate costs from stock, mileage, or hours at request time.

See it in Fieldmotion

CRM1

Open a customer and select Financials. Filter Network requests for Customer_financialsGetDT, then change dates, job type, department, status, search, or sorting. CRM1 hides the page when the user’s CRM access mask includes 32; the endpoint does not repeat that page-permission check.

CRM2

A source search found no CRM2 caller for this customer Financials data table.

Related endpoints