Read Job completion against due dates

When to use this endpoint

Compare completed and incomplete Jobs in a due-date cohort, including the legacy on-time percentage. Select the matching saved Reports dashboard chart or table, choose a bounded range, and use the returned series to render that report.

res rows are percentage, all due Jobs, on-time completed, late completed, and incomplete. The internal completed series includes incomplete Jobs in its denominator.

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

Parameter	Type	Required	Description
`daysFrom`	Integer string	Yes	Inclusive first date: relative day offset from current PHP time by default, or Unix seconds with durationType=1. Must be an integer; malformed/blank values are rejected. ISO strings are not parsed as dates.
`daysTo`	Integer string	Yes	Inclusive last date, in the same mode as daysFrom. Expanded to 23:59:59 in the account timezone; no reversed-range validation.
`durationType`	Integer string	No	Default 0. Exactly 1 uses Unix seconds; other values convert integer day offsets through strtotime. Use 0/1; numeric values are validated before report SQL.
`frequency`	Integer string	No	Default 0 monthly, 1 weekly, 2 quarterly, 3 yearly. Controls helper axis and grouping, using ISO week-year for weekly periods. Unsupported values are rejected.
`userType`	Integer string	Yes	0 summary, 1 users, 2 customers, 3 asset-axis labels. User grouping is created_by for Invoices and assigned user_id for Jobs. Type 3 uses the same customer-key grouping as type 2 rather than an actual asset relationship.
`user`	Native array of ID strings or ["All"]	No	Defaults to ["All"]; a supplied empty list is rejected. Summary ignores the selection; individual axes include selected IDs by name. Pass a native array, not an encoded JSON string.
`displayType`	Integer string	Yes	0 count; 1 linked Job value. Other values fall back to count. Monetary aggregates are integer-converted; this is not a precise ledger export.
`jobType`	Nonempty native array of numeric ID strings	Yes	Job type IDs to include. No server-side All expansion. The dashboards resolve All to actual JobTypes_list IDs before sending; empty or malformed lists are rejected.

Example request

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

Example response

{
  "res": [
    [
      75
    ],
    [
      4
    ],
    [
      3
    ],
    [
      0
    ],
    [
      1
    ]
  ],
  "xLabels": [
    "Jan 2026"
  ],
  "xLabels1": []
}

Populated fixture: three on-time completed and one incomplete Job produce total due 4 and 75%, not a completion-only denominator.

res rows are percentage, all due Jobs, on-time completed, late completed, and incomplete. The internal completed series includes incomplete Jobs in its denominator.

Errors and unusual responses

Response	Condition
`{"error":"not logged in"}`	No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs.
`{"error":"This legacy report does not support your configured record scope. Use the scoped Contracts reports or table exports."}`	The dispatcher detects configured TeamAccess record scope before the handler.
`{"error":"no permission to access api"}`	Account reporting feature bit 8192 is absent.
`{"error":"missing parameter: daysFrom"}`	The named parameter is omitted or null. Present blank/malformed controls return an invalid-parameter error instead; list controls must be native arrays.
`{"error":"missing parameter: daysTo"}`	The named parameter is omitted or null. Present blank/malformed controls return an invalid-parameter error instead; list controls must be native arrays.
`{"error":"missing parameter: userType"}`	The named parameter is omitted or null. Present blank/malformed controls return an invalid-parameter error instead; list controls must be native arrays.
`{"error":"missing parameter: displayType"}`	The named parameter is omitted or null. Present blank/malformed controls return an invalid-parameter error instead; list controls must be native arrays.
`{"error":"missing parameter: jobType"}`	The named parameter is omitted or null. Present blank/malformed controls return an invalid-parameter error instead; list controls must be native arrays.
`{"error":"invalid parameter: daysFrom"}`	A supplied numeric/list control is malformed, a list contains unsupported tokens, or frequency/userType/date selectors are outside 0–3. The message names the invalid control; validation precedes chart queries.

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 due_date, selected Job types and completion state; meeting_time_e and date_completed do not define the cohort. Completed and incomplete rows are read separately.
The confirmed business rule is DATEDIFF(date_completed,due_date) <= 30: completion up to 30 calendar days after the due date is on time, while day 31 is late. Negative differences also qualify; a null difference follows the late branch. The 30-day grace period is intentional.
The second series first accumulates completed rows and then adds incomplete rows. The percentage is floor(onTime / allDue * 100), not completed/all and not onTime/completed. Empty or nonpositive denominators leave percentage zero.
displayType=1 uses linked monetary values for every series and the percentage denominator, so it becomes a value-weighted percentage rather than a count-based completion rate.
Due dates outside the range, null due dates and unselected types do not appear. The SQL explicitly includes is_complete 0 and 1 only; other configured states are omitted.
Linked Job value is computed once per Job: sum the net values of distinct type-3 linked Invoice IDs; if that sum is null, sum distinct type-2 linked Quote IDs; if null, use guarded meta.job_value, otherwise zero. Equal-valued documents remain separate contributions; duplicate links do not multiply values. An explicit zero sum stops fallback. No new deleted-finance filter or direct-link relationship is introduced, and current Job price_net is not used.
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.
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 Jobs Completed (Ref: Due Date), choose filters and inspect Network for Report_getJobsCompleted. 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 Jobs Completed (Ref: Due Date), choose filters and inspect Network for Report_getJobsCompleted. 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

Report_getJobsCompletedItemize — Compare the completion-period matrix with the due-date KPI; their cohorts and percentages differ.
Report_getJobsDue — Inspect currently incomplete Jobs by scheduled date.
ReportDashboard_getRequestedDetails reads a saved widget definition and filters; its widget ID is not a legacy report-template ID.