Read Job profit and expenditure series

When to use this endpoint

Compare Job labour, mileage and stock costs with linked Invoice charges in the Profit and Expenditure Summary report. Select the matching saved Reports dashboard chart or table, choose a bounded range, and use the returned series to render that report.

res rows follow the selected status list; default order is labour, mileage, stock, profit and price charged. It returns xLabels/xLabels1 but not yLabels.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. The handler requires login and account reporting feature bit 8192. No separate Reports, Jobs, Tasks or finance page-permission check is added by the handler.

The dispatcher rejects this legacy Report route for configured TeamAccess record scope, including assigned-only/parent-manager access and applicable department hierarchy scope. It returns an explicit scope error rather than a silently filtered chart.

Allowed requests read the authenticated tenant. Entity selections are report filters or label controls, not authorization; the handler does not add customer account-manager ownership filtering.

Parameters

Example request

$report = FM_api('Report_getUsersSummary', [
	'daysFrom'=>'1768003200',
	'daysTo'=>'1768003200',
	'durationType'=>'1',
	'userType'=>'0',
	'frequency'=>'0',
	'user'=>['All'],
]);

Example response

{
  "res": [
    [
      10
    ],
    [
      2
    ],
    [
      3
    ],
    [
      15
    ],
    [
      30
    ]
  ],
  "xLabels": [
    "Jan 2026"
  ],
  "xLabels1": []
}

Populated fixture: labour 10.9, mileage 2.9, stock 3.9 and price 30.9 are truncated to 10, 2, 3 and 30; profit is 15.

res rows follow the selected status list; default order is labour, mileage, stock, profit and price charged. It returns xLabels/xLabels1 but not yLabels.

Errors and unusual responses

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

Behaviour and edge cases

• Filters active Jobs by scheduled meeting_time_e with Unix day bounds. It groups assigned user_id, or customer_id for customer/asset-axis modes; completion state does not restrict the cohort.
• Labour, mileage and stock are SUM(hours_cost), SUM(mileage_cost), SUM(stock_cost). Price Charged is SUM(invoices.total), not total_net or the Job’s current price_net. No Quote or meta.job_value fallback is applied.
• Invoice links are type-3 Job-to-Invoice rows only. Distinct linked Invoice IDs are summed per Job before outer aggregation, so duplicate links do not repeat charges and multiple Invoices do not multiply Job costs. Type-4/direct links remain outside this contract.
• Each SQL group’s cost/price sums are integer-converted before accumulation. Profit is integer price minus integer labour+mileage+stock. Schedule of Rates cost is not part of this total cost.
• status is a metric selector here, not Job completion state: 0 labour, 1 mileage, 2 stock, 3 profit, 4 price. Request order determines res order, duplicate IDs duplicate contributions and unknown IDs initialize zero rows.
• legend and displayType do not change the server calculation; the saved Reports dashboard uses its own legend selection to show/hide returned metrics.
• There is no pagination, checkpoint or result-size limit. Keep the date range and entity selection bounded. Aggregated values are numeric chart cells, not database scalar strings or object rows.
• The helper orders periods first, then entities by name; one entity collapses xLabels to period text with empty xLabels1. Temporary users with non-null meta.is_tmp are excluded from user-axis lookups, but inactive/deleted label entities are not generally excluded. Unmatched entity/date keys are silently dropped.
• PHP date conversion uses the account timezone (missing/null defaults to Europe/Dublin, blank means UTC). SQL date/Unix conversion uses its database session timezone; these handlers do not force cross-layer alignment.
• Weekly axes enumerate real Mondays and use ISO week-year keys consistently with SQL. Week 53 and ranges crossing a calendar-year boundary are included; display labels are Week NN YYYY using the ISO year.
• For scheduled Unix boundaries, Core_timeLocalToEpoch uses UTC when the timezone setting is blank/missing, while the chart timezone helper uses Europe/Dublin when missing. Configure a valid account timezone to avoid that fallback mismatch.
• Numeric controls and native selector lists are validated through Report_validateChartRequest before SQL. JSON-encoded list strings, nested/object-keyed arrays, unsafe ID values and undocumented tokens are rejected. The existing login, reporting-feature and TeamAccess entry policies remain unchanged.
• No direct caller for this endpoint was found in the mobile app or its m-service intermediary.

Side effects

• Reads tenant data only; no business-record, audit, notification or schema writes occur. The chart restores its temporary PHP timezone on normal return paths.

See it in Fieldmotion

CRM1

Open Reports dashboard, add or preview Profit and Expenditure Summary, choose filters and inspect Network for Report_getUsersSummary. pageReportDashboard.js constructs the endpoint dynamically from the saved api value. Generic legends can control presentation without changing the backend cohort; compare the actual request with this page’s parameter contract.

CRM2

Open Reports dashboard, add or preview Profit and Expenditure Summary, choose filters and inspect Network for Report_getUsersSummary. lib/displayReport.js / pageReportDashboardDetails.js constructs the endpoint dynamically from the saved api value. Generic legends can control presentation without changing the backend cohort; compare the actual request with this page’s parameter contract.

Related endpoints

• ReportDashboard_getRequestedDetails reads a saved widget definition and filters; its widget ID is not a legacy report-template ID.