Fieldmotion API Getting started

Contracts

Build the contract labour-budget table

POST /a/Contracts_getLabourBudgetsDT

Build CRM1’s active-contract labour-budget table with budgeted hours, completed-job labour totals, and direct completed-job timestamps.

When to use this endpoint

Use Contracts_getLabourBudgetsDT only for CRM1’s Contract Labour screen and its positional ten-field rows.

Use Contract_setHoursBudget to change the budget shown here.

Authentication and permissions

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

Parameters

ParameterTypeRequiredDescription
drawInteger stringYesPresence is required; the integer-converted value is echoed. Blank is accepted as 0.
startInteger stringNoZero-based offset; defaults to 0.
lengthInteger stringNoPage size; defaults to 1.
search[value]StringNoWhen nonblank, substring-searches contract name or expiry date.
order[0][column]Integer stringNo0 sorts by name, 2 by expiry date, and any other supplied index by ID. Omission leaves database order unspecified.
order[0][dir]StringWith order columnExact asc selects ascending; all other values select descending.

Example request

$table = FM_api('Contracts_getLabourBudgetsDT', [
	'draw' => '2',
	'start' => '0',
	'length' => '25',
	'order' => [['column' => '0', 'dir' => 'asc']],
]);

Example response

{
  "draw": 2,
  "recordsTotal": "12",
  "recordsFiltered": "12",
  "data": [
    [
      "720", "North Region Service Contract", "[8801,8802]", 120,
      "1200.00", "16.00", "2026-01-10 09:30:00", "1", "2026-12-31",
      [["8801", "2026-03-10 09:00:00"]]
    ]
  ]
}

Row positions are contract ID, name, JSON job-ID array, floating-point hours budget, completed-job labour cost, completed-job hours, creation date, active value, expiry date, and direct completed-job [ID, tenant-local job time] arrays.

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: draw"}draw is absent.
Authentication errorNo valid API signature or logged-in CRM session is available.

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 active contracts are returned and counted. There is no completed/all-status option.
  • Job IDs exclude soft-deleted jobs. Labour cost and hours include only jobs whose is_complete value is nonzero.
  • The hours budget is read from meta.hours_budget and converted to a float; missing or malformed metadata produces zero.
  • Detail timestamps are converted from the stored epoch to the tenant’s local time. A failed conversion omits that job from the detail array.

See it in Fieldmotion

CRM1

Open Contract Labour. Search, sort, or page the table; budget edits use Contract_setHoursBudget and reload this route.

CRM2

A production-source search found no direct CRM2 caller; CRM2 uses its newer contract labour models.

Related endpoints