Fieldmotion API Getting started

Assets

List mapped asset financials

POST /a/Asset_financialsGetDataTable

Query mapped job fields and enrich each row with current SOR costs and linked-invoice totals.

When to use this endpoint

Use Asset_financialsGetDataTable when a configurable table needs named job fields plus calculated asset-financial values.

It is not automatically scoped to an asset. Callers must pass the mapped customerID and customerType filters themselves.

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
fieldsArray of stringsYesMapped Job field names to return, such as id, jobRef, meetingTime, hoursCost, mileageCost, and stockCost. It must be a request array. The handler always adds scheduleOfRates and scheduleOfRates2 to the returned rows.
customerIDInteger string or arrayFor asset scopingExact job customer ID filter. Without it, the route can return jobs from across the tenant.
customerTypeInteger string or arrayFor asset scopingUse 1 with customerID to restrict the result to direct jobs for an asset.
start / length / drawInteger stringsNoDataTables offset, page size, and echoed token; defaults are 0, 10, and 0.
orderDataTables arrayNoThe column index is reduced by one before selecting a field from fields. Direction is desc only on an exact match; default ordering is the first recognized field ascending.
orderBy / orderDescStringsNoAlternative mapped field and direction. Field matching is case-insensitive; the direction text is passed through by the generic helper.
searchValue / searchFieldString / string or arrayNoGeneric case-insensitive mapped-field search. searchField defaults to All.
<mapped field>Scalar or arrayNoAny recognized Job map key becomes a filter. Text uses substring matching; numeric values use exact integer matching; arrays become IN filters.
referenceDate and date/time controlsMixedNoGeneric relative-day and hour filtering. referenceDate must name a mapped date field; dateFrom/dateTo are integer day offsets from today, not ISO dates.
advanceSearchArrayNoLegacy generic filter clauses. Raw where clauses are for trusted internal composition only.

Example request

$page = FM_api('Asset_financialsGetDataTable', [
	'customerID' => '4821',
	'customerType' => '1',
	'fields' => ['id', 'jobRef', 'meetingTime', 'hoursCost', 'stockCost'],
	'draw' => '1',
	'start' => '0',
	'length' => '10',
]);

Example response

{
  "data": [{
    "id": "7719",
    "jobRef": "JOB-7719",
    "meetingTime": "2026-09-24 09:00:00",
    "hoursCost": "125.00",
    "stockCost": "40.00",
    "scheduleOfRates": "[[12,1]]",
    "scheduleOfRates2": "[]",
    "sorCost": 52.5,
    "jobSorStock": 12.5,
    "jobSorLabour": 40,
    "invStockTotal": 120,
    "invSorTotal": 60,
    "invLabourTotal": 100,
    "invMileageTotal": 20,
    "invMiscTotal": 0,
    "invTotal": 300
  }],
  "draw": 1,
  "recordsTotal": "940",
  "recordsFiltered": "1"
}

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"}fields is absent.
{"error":"error in database query"}The generic field/filter combination produces invalid SQL.

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 jobs are excluded. recordsTotal counts all non-deleted tenant jobs, while recordsFiltered applies the supplied map filters.
  • SOR values are estimated from current stock average costs and current SOR labour definitions. Stored SOR row quantity is read but is not applied to the estimate.
  • Invoice totals use non-deleted invoices linked with supported job/invoice link types. Only parsed invoice rows with the current job ID contribute; an old invoice with no rows contributes its entire total.
  • The route appends its calculated fields to every returned object and is read-only. It performs per-row invoice lookups, so large pages can be expensive.

See it in Fieldmotion

CRM1

No direct production CRM1 caller was found; CRM1 uses Asset_financialsGetDT.

CRM2

No current direct string caller was found in production CRM2 source. The endpoint follows CRM2’s generic named-field table contract and has live regression coverage.

Related endpoints